[camel] branch master updated: improve the documentation of useMessageBodyForSql (#3631)

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git


The following commit(s) were added to refs/heads/master by this push:
     new 4443c94  improve the documentation of useMessageBodyForSql (#3631)
4443c94 is described below

commit 4443c94b048c79463b0cc79ee7c7fc58dbe600be
Author: Volker Börchers <vb...@web.de>
AuthorDate: Fri Mar 13 09:28:43 2020 +0100

    improve the documentation of useMessageBodyForSql (#3631)
    
    include the common search term 'conditional processing'
    add a note about the changed named parameter placeholder
    
    Co-authored-by: Volker Boerchers <vb...@users.noreply.github.com>
---
 .../resources/org/apache/camel/component/sql/sql.json         |  2 +-
 components/camel-sql/src/main/docs/sql-component.adoc         | 11 +++++++----
 .../org/apache/camel/component/sql/DefaultSqlEndpoint.java    |  2 +-
 .../camel/builder/endpoint/dsl/SqlEndpointBuilderFactory.java |  6 ++++--
 4 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/components/camel-sql/src/generated/resources/org/apache/camel/component/sql/sql.json b/components/camel-sql/src/generated/resources/org/apache/camel/component/sql/sql.json
index 6057870..8461ee3 100644
--- a/components/camel-sql/src/generated/resources/org/apache/camel/component/sql/sql.json
+++ b/components/camel-sql/src/generated/resources/org/apache/camel/component/sql/sql.json
@@ -52,7 +52,7 @@
     "batch": { "kind": "parameter", "displayName": "Batch", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Enables or disables batch mode" },
     "lazyStartProducer": { "kind": "parameter", "displayName": "Lazy Start Producer", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the  [...]
     "noop": { "kind": "parameter", "displayName": "Noop", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "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" },
-    "useMessageBodyForSql": { "kind": "parameter", "displayName": "Use Message Body For Sql", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used." },
+    "useMessageBodyForSql": { "kind": "parameter", "displayName": "Use Message Body For Sql", "group": "producer", "label": "producer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used. Note that query parameters in the message body are represented by a question ma [...]
     "alwaysPopulateStatement": { "kind": "parameter", "displayName": "Always Populate Statement", "group": "advanced", "label": "advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "If enabled then the populateStatement method from org.apache.camel.component.sql.SqlPrepareStatementStrategy is always invoked, also if there is no expected parameters to be prepared. When this is false then the po [...]
     "basicPropertyBinding": { "kind": "parameter", "displayName": "Basic Property Binding", "group": "advanced", "label": "advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities" },
     "parametersCount": { "kind": "parameter", "displayName": "Parameters Count", "group": "advanced", "label": "advanced", "required": false, "type": "integer", "javaType": "int", "deprecated": false, "secret": false, "description": "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." },
diff --git a/components/camel-sql/src/main/docs/sql-component.adoc b/components/camel-sql/src/main/docs/sql-component.adoc
index 40c6aed..282aea0 100644
--- a/components/camel-sql/src/main/docs/sql-component.adoc
+++ b/components/camel-sql/src/main/docs/sql-component.adoc
@@ -180,7 +180,7 @@ with the following path and query parameters:
 | *batch* (producer) | Enables or disables batch mode | false | boolean
 | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and [...]
 | *noop* (producer) | 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 | false | boolean
-| *useMessageBodyForSql* (producer) | Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used. | false | boolean
+| *useMessageBodyForSql* (producer) | Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used. Note that query parameters in the message body are represented by a question mark instead of a # symbol. | false | boolean
 | *alwaysPopulateStatement* (advanced) | If enabled then the populateStatement method from org.apache.camel.component.sql.SqlPrepareStatementStrategy is always invoked, also if there is no expected parameters to be prepared. When this is false then the populateStatement 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. | false | boolean
 | *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
 | *parametersCount* (advanced) | 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. |  | int
@@ -227,11 +227,14 @@ 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.
 
-You can use the option useMessageBodyForSql that
+You can use the option `useMessageBodyForSql` that
 allows to use the message body as the SQL statement, and then the SQL
 parameters must be provided in a header with the
-key SqlConstants.SQL_PARAMETERS. This allows the SQL component to work
-more dynamic as the SQL query is from the message body.
+key `SqlConstants.SQL_PARAMETERS`. This allows the SQL component to work
+more dynamically as the SQL query is from the message body. Use
+https://camel.apache.org/manual/latest/templating.html[Camel templating]
+for conditional processing, e.g. to include or exclude `where` clauses
+depending on the presence of query parameters.
 
 == Result of the query
 
diff --git a/components/camel-sql/src/main/java/org/apache/camel/component/sql/DefaultSqlEndpoint.java b/components/camel-sql/src/main/java/org/apache/camel/component/sql/DefaultSqlEndpoint.java
index 7b34314..73e1b24 100644
--- a/components/camel-sql/src/main/java/org/apache/camel/component/sql/DefaultSqlEndpoint.java
+++ b/components/camel-sql/src/main/java/org/apache/camel/component/sql/DefaultSqlEndpoint.java
@@ -109,7 +109,7 @@ public abstract class DefaultSqlEndpoint extends DefaultPollingEndpoint {
             + " in the message body, any existing content in the message body is discarded. If outputHeader is set, the value is used as the name of the header"
             + " to store the query result and the original message body is preserved.")
     private String outputHeader;
-    @UriParam(label = "producer", description = "Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used.")
+    @UriParam(label = "producer", description = "Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used. Note that query parameters in the message body are represented by a question mark instead of a <tt>#</tt> symbol.")
     private boolean useMessageBodyForSql;
     @UriParam(label = "advanced", defaultValue = "#", description = "Specifies a character that will be replaced to ? in SQL query."
             + " Notice, that it is simple String.replaceAll() operation and no SQL parsing is involved (quoted strings will also change).")
diff --git a/core/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/SqlEndpointBuilderFactory.java b/core/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/SqlEndpointBuilderFactory.java
index 9281d0b..4e3099e 100644
--- a/core/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/SqlEndpointBuilderFactory.java
+++ b/core/camel-endpointdsl/src/generated/java/org/apache/camel/builder/endpoint/dsl/SqlEndpointBuilderFactory.java
@@ -1480,7 +1480,8 @@ public interface SqlEndpointBuilderFactory {
         /**
          * Whether to use the message body as the SQL and then headers for
          * parameters. If this option is enabled then the SQL in the uri is not
-         * used.
+         * used. Note that query parameters in the message body are represented
+         * by a question mark instead of a # symbol.
          * 
          * The option is a: <code>boolean</code> type.
          * 
@@ -1495,7 +1496,8 @@ public interface SqlEndpointBuilderFactory {
         /**
          * Whether to use the message body as the SQL and then headers for
          * parameters. If this option is enabled then the SQL in the uri is not
-         * used.
+         * used. Note that query parameters in the message body are represented
+         * by a question mark instead of a # symbol.
          * 
          * The option will be converted to a <code>boolean</code> type.
          *