Modified: websites/production/camel/content/sql-component.html
==============================================================================
--- websites/production/camel/content/sql-component.html (original)
+++ websites/production/camel/content/sql-component.html Mon Aug 11 07:19:09
2014
@@ -110,18 +110,12 @@
<p>The SQL component uses the following endpoint URI notation:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[sql:select * from table where id=# order by
name[?options]
]]></script>
-</div></div><p>From Camel 2.11 onwards you can use named parameters by using
<code>#:name</code> style as shown:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>From Camel 2.11 onwards you can use named parameters by using
:<code>#name_of_the_parameter</code> style as shown:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[sql:select * from table where id=:#myId order
by name[?options]
]]></script>
</div></div><p>When using named parameters, Camel will lookup the names from,
in the given precedence:<br clear="none"> 1. from message body if its a
<code>java.util.Map</code><br clear="none"> 2. from message headers</p><p>If a
named parameter cannot be resolved, then an exception is thrown.</p><p>From
Camel 2.14 onward you can use Simple expressions as parameters as
shown:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[sql:select * from table where
id=:#${property.myId} order by name[?options]]]></script>
-</div></div><p>Notice that the standard <code>?</code> symbol that denotes the
parameters to an SQL query is substituted with the <code>#</code> symbol,
because the <code>?</code> symbol is used to specify options for the endpoint.
The <code>?</code> symbol replacement can be configured on endpoint
basis.</p><p>You can append query options to the URI in the following format,
<code>?option=value&option=value&...</code></p><h3
id="SQLComponent-Options">Options</h3><div class="confluenceTableSmall">
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh"><p> Option </p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p> Type </p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p> Default </p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p> Description </p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>batch</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>boolean</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>false</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <strong>Camel 2.7.5, 2.8.4 and
2.9:</strong> Execute SQL batch update statements. See notes below on how the
treatment of the inbound message body changes if this is set to
<code>true</code>. </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>dataSourceRef</code> </p></td><td colspan="1"
rowspan="1" class="confluence
Td"><p> <code>String</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>null</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Deprecated and will be removed in Camel
3.0:</strong> Reference to a <code>DataSource</code> to look up in the
registry. Use <code>dataSource=#theName</code> instead. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>dataSource</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>String</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>null</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11:</strong> Reference to a
<code>DataSource</code> to look up in the registry. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>placeholder</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>String</code> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><
p> <code>#</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.4:</strong> Specifies a character that
will be replaced to <code>?</code> in SQL query. Notice, that it is simple
<code>String.replaceAll()</code> operation and no SQL parsing is involved
(quoted strings will also change). This replacement is <strong>only</strong>
happening if the endpoint is created using the <code>SqlComponent</code>. If
you manually create the endpoint, then use the expected <code>?</code> sign
instead. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>template.<xxx></code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>null</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> Sets additional options on the Spring
<code>JdbcTemplate</code> that is used behind the scenes to execute the
queries. For instance, <code>template.maxRows=10</
code>. For detailed documentation, see the <a shape="rect"
class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/jdbc/core/JdbcTemplate.html";
rel="nofollow">JdbcTemplate javadoc</a> documentation. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>
<code>allowNamedParameters</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>boolean</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>true</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <strong>Camel 2.11:</strong> Whether to
allow using named parameters in the queries. </p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>processingStrategy</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <strong>Camel 2.11:</strong> <strong
>SQL consumer only:</strong> Allows to plugin to use a custom
><code>org.apache.camel.component.sql.SqlProcessingStrategy</code> to execute
>queries when the consumer has processed the rows/batch. </p></td></tr><tr><td
>colspan="1" rowspan="1" class="confluenceTd"><p>
><code>prepareStatementStrategy</code> </p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p> <strong>Camel 2.11:</strong> Allows to plugin to use
>a custom
><code>org.apache.camel.component.sql.SqlPrepareStatementStrategy</code> to
>control preparation of the query and prepared statement.
></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
><code>consumer.delay</code> </p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p> <code>long</code> </p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p> <code>500</code> </p></td><td
>colspan="1" rowspan="1" class="c
onfluenceTd"><p> <strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> Delay in milliseconds between each poll. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>
<code>consumer.initialDelay</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>long</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>1000</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> Milliseconds before polling starts. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>
<code>consumer.useFixedDelay</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>boolean</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>false</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel 2.11:</strong>
<strong>SQL consumer only:</strong> Set to <code>true</code> to use fixed delay
bet
ween polls, otherwise fixed rate is used. See <a shape="rect"
class="external-link"
href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ScheduledExecutorService.html";
rel="nofollow">ScheduledExecutorService</a> in JDK for details.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>maxMessagesPerPoll</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>int</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>0</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> An integer value to define the maximum number of messages to
gather per poll. By default, no maximum is set. </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>
<code>consumer.useIterator</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>boolean</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>
true</code> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<strong>Camel 2.11:</strong> <strong>SQL consumer only:</strong> If
<code>true</code> each row returned when polling will be processed
individually. If <code>false</code> the entire <code>java.util.List</code> of
data is set as the IN body. </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>consumer.routeEmptyResultSet</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>boolean</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>false</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> Whether to route a single empty <a shape="rect"
href="exchange.html">Exchange</a> if there was no data to poll.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>consumer.onConsume</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <
code>String</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>null</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> After processing each row then this query can be executed, if
the <a shape="rect" href="exchange.html">Exchange</a> was processed
successfully, for example to mark the row as processed. The query can have
parameter. </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>consumer.onConsumeFailed</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>String</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <code>null</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel
2.11:</strong> <strong>SQL consumer only:</strong> After processing each row
then this query can be executed, if the <a shape="rect"
href="exchange.html">Exchange</a> failed, for example to mark the row as f
ailed. The query can have parameter. </p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>
<code>consumer.onConsumeBatchComplete</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>String</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>null</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel 2.11:</strong>
<strong>SQL consumer only:</strong> After processing the entire batch, this
query can be executed to bulk update rows etc. The query cannot have
parameters. </p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>consumer.expectedUpdateCount</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>int</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>-1</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel 2.11:</strong>
<strong>SQL consumer only:</strong> If using <code>consumer.onConsume</co
de> then this option can be used to set an expected number of rows being
updated. Typically you may set this to <code>1</code> to expect one row to be
updated. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>consumer.breakBatchOnConsumeFail</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>boolean</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>false</code>
</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel
2.11:</strong> <strong>SQL consumer only:</strong> If using
<code>consumer.onConsume</code> and it fails, then this option controls whether
to break out of the batch or continue processing the next row from the batch.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>alwaysPopulateStatement</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>boolean</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>fal
se</code> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<strong>Camel 2.11:</strong> <strong>SQL producer only:</strong> If enabled
then the <code>populateStatement</code> method from
<code>org.apache.camel.component.sql.SqlPrepareStatementStrategy</code> is
always invoked, also if there is no expected parameters to be prepared. When
this is <code>false</code> then the <code>populateStatement</code> is only
invoked if there is 1 or more expected parameters to be set; for example this
avoids reading the message body/headers for SQL queries with no parameters.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>separator</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>char</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>,</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.11.1:</strong> The separator to use
when parameter values is taken from message body (i
f the body is a String type), to be inserted at # placeholders. Notice if you
use named parameters, then a <code>Map</code> type is used instead.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>outputType</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>String</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>SelectList</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel 2.12.0:</strong>
Make the output of consumer or producer to <code>SelectList</code> as List of
Map, or <code>SelectOne</code> as single Java object in the following way:<br
clear="none">
-a) If the query has only single column, then that JDBC Column object is
returned. (such as <code>SELECT COUNT( * ) FROM PROJECT</code> will return a
Long object.<br clear="none">
-b) If the query has more than one column, then it will return a Map of that
result.<br clear="none">
-c) If the <code>outputClass</code> is set, then it will convert the query
result into an Java bean object by calling all the setters that match the
column names. It will assume your class has a default constructor to create
instance with.<br clear="none">
-d) If the query resulted in more than one rows, it throws an non-unique result
exception.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p> <code>outputClass</code> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>String</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>null</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel 2.12.0:</strong>
Specify the full package and class name to use as conversion when
<code>outputType=SelectOne</code>. </p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p> <code>parametersCount</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>int</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <code>0</code> </p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> <strong>Camel
2.11.2/2.12.0</strong> If set greater than zero, then Camel will use this count
value of parameters to replace instead of qu
erying via JDBC metadata API. This is useful if the JDBC vendor could not
return correct parameters count, then user may override instead.
</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>noop</code> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>
<code>boolean</code> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> false </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p> <strong>Camel 2.12.0</strong> If set, will ignore the
results of the SQL query and use the existing IN message as the OUT message for
the continuation of processing </p></td></tr></tbody></table></div>
-</div><h3 id="SQLComponent-Treatmentofthemessagebody">Treatment of the message
body</h3><p>The SQL component tries to convert the message body to an object of
<code>java.util.Iterator</code> type and then uses this iterator to fill the
query parameters (where each query parameter is represented by a <code>#</code>
symbol (or configured placeholder) in the endpoint URI). If the message body is
not an array or collection, the conversion results in an iterator that iterates
over only one object, which is the body itself.</p><p>For example, if the
message body is an instance of <code>java.util.List</code>, the first item in
the list is substituted into the first occurrence of <code>#</code> in the SQL
query, the second item in the list is substituted into the second occurrence of
<code>#</code>, and so on.</p><p>If <code>batch</code> is set to
<code>true</code>, then the interpretation of the inbound message body changes
slightly – instead of an iterator of parameters, the compone
nt expects an iterator that contains the parameter iterators; the size of the
outer iterator determines the batch size.</p><h3
id="SQLComponent-Resultofthequery">Result of the query</h3><p>For
<code>select</code> operations, the result is an instance of
<code>List<Map<String, Object>></code> type, as returned by the <a
shape="rect" class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/jdbc/core/JdbcTemplate.html#queryForList(java.lang.String,%20java.lang.Object%91%93)"
rel="nofollow">JdbcTemplate.queryForList()</a> method. For <code>update</code>
operations, the result is the number of updated rows, returned as an
<code>Integer</code>.</p><h3 id="SQLComponent-Headervalues">Header
values</h3><p>When performing <code>update</code> operations, the SQL Component
stores the update count in the following message headers:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="conf
luenceTh"><p>Header</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>CamelSqlUpdateCount</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The number of rows updated for
<code>update</code> operations, returned as an <code>Integer</code>
object.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSqlRowCount</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The number of rows returned for
<code>select</code> operations, returned as an <code>Integer</code>
object.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSqlQuery</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Query to
execute. This query takes precedence over the query specified in the endpoint
URI. Note that query parameters in the header <em>are</em> represented by a
<code>?</code> instead
of a <code>#</code> symbol</p></td></tr></tbody></table></div><p>When
performing <code>insert</code> operations, the SQL Component stores the
rows with the generated keys and number of these rown in the following message
headers (<strong>Available as of Camel 2.12.4, 2.13.1</strong>):</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Header</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><pre>CamelSqlGeneratedKeysRowCount</pre></td><td
colspan="1" rowspan="1" class="confluenceTd">The number of rows in the header
that contains generated keys.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><pre>CamelSqlGeneratedKeyRows</pre></td><td colspan="1"
rowspan="1" class="confluenceTd"> Rows that contains the generated keys (a
list of maps of keys).</td></tr></tbody></table></div><h3
id="SQLComponent-Generated
keys">Generated keys</h3><p><strong>Available as of Camel 2.12.4, 2.13.1 and
2.14<br clear="none"></strong></p><p>If you insert data using SQL INSERT, then
the RDBMS may support auto generated keys. You can instruct the SQL producer to
return the generated keys in headers.<br clear="none"> To do that set the
header <code>CamelSqlRetrieveGeneratedKeys=true</code>. Then the generated keys
will be provided as headers with the keys listed in the table above.</p><p>You
can see more details in this <a shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=camel.git;a=blob_plain;f=components/camel-sql/src/test/java/org/apache/camel/component/sql/SqlGeneratedKeysTest.java;hb=3962b23f94bb4bc23011b931add08c3f6833c82e";>unit
test</a>.</p><h3 id="SQLComponent-Configuration">Configuration</h3><p>You can
now set a reference to a <code>DataSource</code> in the URI directly:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl
">
+</div></div><p>Notice that the standard <code>?</code> symbol that denotes the
parameters to an SQL query is substituted with the <code>#</code> symbol,
because the <code>?</code> symbol is used to specify options for the endpoint.
The <code>?</code> symbol replacement can be configured on endpoint
basis.</p><p>You can append query options to the URI in the following format,
<code>?option=value&option=value&...</code></p><h3
id="SQLComponent-Options">Options</h3><div class="confluenceTableSmall"><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Type</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Default</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>batch</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>bool
ean</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>false</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.7.5, 2.8.4 and 2.9:</strong> Execute
SQL batch update statements. See notes below on how the treatment of the
inbound message body changes if this is set to
<code>true</code>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>dataSourceRef</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Deprecated and will be removed in
Camel 3.0:</strong> Reference to a <code>DataSource</code> to look up in the
registry. Use <code>dataSource=#theName</code> instead.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>dataSource</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>String<
/code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>null</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.11:</strong> Reference to a
<code>DataSource</code> to look up in the registry.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>placeholder</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>#</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.4:</strong> Specifies a
character that will be replaced to <code>?</code> in SQL query. Notice, that it
is simple <code>String.replaceAll()</code> operation and no SQL parsing is
involved (quoted strings will also change). This replacement is
<strong>only</strong> happening if the endpoint is created using the
<code>SqlComponent</code>. If you manually create the endpoint, then use the
expected <code>?</code> sign instead.</p><
/td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>template.<xxx></code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Sets additional options on the Spring
<code>JdbcTemplate</code> that is used behind the scenes to execute the
queries. For instance, <code>template.maxRows=10</code>. For detailed
documentation, see the <a shape="rect" class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/jdbc/core/JdbcTemplate.html";
rel="nofollow">JdbcTemplate javadoc</a> documentation.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>allowNamedParameters</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> Whether to
allow using named parameters in the queries.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>processingStrategy</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL consumer
only:</strong> Allows to plugin to use a custom
<code>org.apache.camel.component.sql.SqlProcessingStrategy</code> to execute
queries when the consumer has processed the rows/batch.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>prepareStatementStrategy</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.11:</strong> Allows to plugin to
use a custom
<code>org.apache.camel.component.sql.SqlPrepareStatementStrategy</code> to
control preparation of the query and prepared statement.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.delay</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>500</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> Delay in milliseconds between each
poll.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.initialDelay</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>long</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>1000</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong>
<strong>SQL consumer only:</strong> Milliseconds before polling
starts.</p></td></tr>
<tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.useFixedDelay</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> Set to <code>true</code> to use fixed delay between
polls, otherwise fixed rate is used. See <a shape="rect" class="external-link"
href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/concurrent/ScheduledExecutorService.html";
rel="nofollow">ScheduledExecutorService</a> in JDK for
details.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>maxMessagesPerPoll</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>0</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel
2.11:</strong> <strong>SQL consumer only:</strong> An integer value to define
the maximum number of messages to gather per poll. By default, no maximum is
set.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.useIterator</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>true</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> If <code>true</code> each row returned when polling
will be processed individually. If <code>false</code> the entire
<code>java.util.List</code> of data is set as the IN body.</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.routeEmptyResultSet</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p>
</td><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Camel
2.11:</strong> <strong>SQL consumer only:</strong> Whether to route a single
empty <a shape="rect" href="exchange.html">Exchange</a> if there was no data to
poll.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.onConsume</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> After processing each row then this query can be
executed, if the <a shape="rect" href="exchange.html">Exchange</a> was
processed successfully, for example to mark the row as processed. The query can
have parameter.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.onConsumeFailed</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"
><p><code>String</code></p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p><code>null</code></p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL consumer
>only:</strong> After processing each row then this query can be executed, if
>the <a shape="rect" href="exchange.html">Exchange</a> failed, for example to
>mark the row as failed. The query can have parameter.</p></td></tr><tr><td
>colspan="1" rowspan="1"
>class="confluenceTd"><p><code>consumer.onConsumeBatchComplete</code></p></td><td
> colspan="1" rowspan="1"
>class="confluenceTd"><p><code>String</code></p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
>consumer only:</strong> After processing the entire batch, this query can be
>executed to bulk update rows etc. The query cannot have
>parameters.</p></td></tr><tr><td colspan="1" rowspan="1" class="conflue
nceTd"><p><code>consumer.expectedUpdateCount</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-1</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> If using <code>consumer.onConsume</code> then this
option can be used to set an expected number of rows being updated. Typically
you may set this to <code>1</code> to expect one row to be
updated.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>consumer.breakBatchOnConsumeFail</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
consumer only:</strong> If using <code>consumer.onConsume</code> and it fails,
then this optio
n controls whether to break out of the batch or continue processing the next
row from the batch.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>alwaysPopulateStatement</code></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>false</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11:</strong> <strong>SQL
producer only:</strong> If enabled then the <code>populateStatement</code>
method from
<code>org.apache.camel.component.sql.SqlPrepareStatementStrategy</code> is
always invoked, also if there is no expected parameters to be prepared. When
this is <code>false</code> then the <code>populateStatement</code> is only
invoked if there is 1 or more expected parameters to be set; for example this
avoids reading the message body/headers for SQL queries with no
parameters.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"
><p><code>separator</code></p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p><code>char</code></p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p><code>,</code></p></td><td colspan="1" rowspan="1"
>class="confluenceTd"><p><strong>Camel 2.11.1:</strong> The separator to use
>when parameter values is taken from message body (if the body is a String
>type), to be inserted at # placeholders. Notice if you use named parameters,
>then a <code>Map</code> type is used instead.</p></td></tr><tr><td
>colspan="1" rowspan="1"
>class="confluenceTd"><p><code>outputType</code></p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td
>colspan="1" rowspan="1"
>class="confluenceTd"><p><code>SelectList</code></p></td><td colspan="1"
>rowspan="1" class="confluenceTd"><p><strong>Camel 2.12.0:</strong> Make the
>output of consumer or producer to <code>SelectList</code> as List of Map, or
><code>SelectOne</code> as single Java object in the following way:<br clea
r="none"> a) If the query has only single column, then that JDBC Column object
is returned. (such as <code>SELECT COUNT( * ) FROM PROJECT</code> will return a
Long object.<br clear="none"> b) If the query has more than one column, then it
will return a Map of that result.<br clear="none"> c) If the
<code>outputClass</code> is set, then it will convert the query result into an
Java bean object by calling all the setters that match the column names. It
will assume your class has a default constructor to create instance with.<br
clear="none"> d) If the query resulted in more than one rows, it throws an
non-unique result exception.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>outputClass</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>String</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>null</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.12.0:</strong> Specify the
full p
ackage and class name to use as conversion when
<code>outputType=SelectOne</code>.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>parametersCount</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>int</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>0</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.11.2/2.12.0</strong> If set
greater than zero, then Camel will use this count value of parameters to
replace instead of querying via JDBC metadata API. This is useful if the JDBC
vendor could not return correct parameters count, then user may override
instead.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>noop</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>boolean</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>false</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong>Camel 2.12.0</strong> If
set, will ignore the results of the SQL query and use the existing IN message
as the OUT message for the continuation of
processing</p></td></tr></tbody></table></div></div><h3
id="SQLComponent-Treatmentofthemessagebody">Treatment of the message
body</h3><p>The SQL component tries to convert the message body to an object of
<code>java.util.Iterator</code> type and then uses this iterator to fill the
query parameters (where each query parameter is represented by a <code>#</code>
symbol (or configured placeholder) in the endpoint URI). If the message body is
not an array or collection, the conversion results in an iterator that iterates
over only one object, which is the body itself.</p><p>For example, if the
message body is an instance of <code>java.util.List</code>, the first item in
the list is substituted into the first occurrence of <code>#</code> in the SQL
query, the second item in the list is substituted into the second occurrence of
<code>#</code>, and so on.</p><p>If <code>b
atch</code> is set to <code>true</code>, then the interpretation of the
inbound message body changes slightly – instead of an iterator of
parameters, the component expects an iterator that contains the parameter
iterators; the size of the outer iterator determines the batch size.</p><h3
id="SQLComponent-Resultofthequery">Result of the query</h3><p>For
<code>select</code> operations, the result is an instance of
<code>List<Map<String, Object>></code> type, as returned by the <a
shape="rect" class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/jdbc/core/JdbcTemplate.html#queryForList(java.lang.String,%20java.lang.Object%91%93)"
rel="nofollow">JdbcTemplate.queryForList()</a> method. For <code>update</code>
operations, the result is the number of updated rows, returned as an
<code>Integer</code>.</p><h3 id="SQLComponent-Headervalues">Header
values</h3><p>When performing <code>update</code> operations, the SQL Component
stores the update count in the following message headers:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Header</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>CamelSqlUpdateCount</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The number of rows updated for
<code>update</code> operations, returned as an <code>Integer</code>
object.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSqlRowCount</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The number of rows returned for
<code>select</code> operations, returned as an <code>Integer</code>
object.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>CamelSqlQuery</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong>Camel 2.8:</strong> Query to
execute.
This query takes precedence over the query specified in the endpoint URI. Note
that query parameters in the header <em>are</em> represented by a
<code>?</code> instead of a <code>#</code>
symbol</p></td></tr></tbody></table></div><p>When
performing <code>insert</code> operations, the SQL Component stores the
rows with the generated keys and number of these rown in the following message
headers (<strong>Available as of Camel 2.12.4, 2.13.1</strong>):</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Header</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><pre>CamelSqlGeneratedKeysRowCount</pre></td><td
colspan="1" rowspan="1" class="confluenceTd">The number of rows in the header
that contains generated keys.</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><pre>CamelSqlGeneratedKeyRows</pre></td><td colspan="
1" rowspan="1" class="confluenceTd"> Rows that contains the generated
keys (a list of maps of keys).</td></tr></tbody></table></div><h3
id="SQLComponent-Generatedkeys">Generated keys</h3><p><strong>Available as of
Camel 2.12.4, 2.13.1 and 2.14<br clear="none"></strong></p><p>If you insert
data using SQL INSERT, then the RDBMS may support auto generated keys. You can
instruct the SQL producer to return the generated keys in headers.<br
clear="none"> To do that set the header
<code>CamelSqlRetrieveGeneratedKeys=true</code>. Then the generated keys will
be provided as headers with the keys listed in the table above.</p><p>You can
see more details in this <a shape="rect" class="external-link"
href="https://git-wip-us.apache.org/repos/asf?p=camel.git;a=blob_plain;f=components/camel-sql/src/test/java/org/apache/camel/component/sql/SqlGeneratedKeysTest.java;hb=3962b23f94bb4bc23011b931add08c3f6833c82e";>unit
test</a>.</p><h3 id="SQLComponent-Configuration">Configuration</h3><p>You can n
ow set a reference to a <code>DataSource</code> in the URI directly:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[sql:select * from table where id=# order by
name?dataSource=myDS
]]></script>
</div></div><h3 id="SQLComponent-Sample">Sample</h3><p>In the sample below we
execute a query and retrieve the result as a <code>List</code> of rows, where
each row is a <code>Map<String, Object</code> and the key is the column
name.</p><p>First, we set up a table to use for our sample. As this is based on
an unit test, we do it in java:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
