diff --git a/docs/src/reference/docbook/jdbc.xml b/docs/src/reference/docbook/jdbc.xml
index c626c50bfc..931a99431a 100644
--- a/docs/src/reference/docbook/jdbc.xml
+++ b/docs/src/reference/docbook/jdbc.xml
@@ -221,22 +221,33 @@
logical name.
+
Stored Procedures
- Spring Integration provides 3 components for stored procedures support:
-
- Stored Procedures Inbound Channel Adapter
- Stored Procedures Outbound Channel Adapter
- Stored Procedures Outbound Gateway
-
-
- Common Configuration Parameters
-
+
+ In certain situations plain JDBC support is not sufficient. Maybe you
+ deal with legacy relational database schemas or you have
+ complex data processing needs, but ultimately you have to use
+ Stored Procedures
+ or Stored Functions. Since Spring Integration 2.1, we provide
+ three components in order to execute Stored Procedures or
+ Stored Functions:
+
+
+ Stored Procedures Inbound Channel Adapter
+ Stored Procedures Outbound Channel Adapter
+ Stored Procedures Outbound Gateway
+
+
- Supported Parameters
- The Store procedures components use the org.springframework.jdbc.core.simple.SimpleJdbcCall
- class to facilitate Stored Procedure support. The following databases
- are fully supported for executing Stored procedures:
+ Supported Databases
+
+ In order to enable calls to Stored Procedures
+ and Stored Functions, the Stored Procedure
+ components use the org.springframework.jdbc.core.simple.SimpleJdbcCall
+ class. Consequently, the following databases are fully supported
+ for executing Stored Procedures:
Apache Derby
DB2
@@ -245,268 +256,604 @@
Oracle
PostgreSQL
Sybase
-
- The following databases are fully supported for executing Sql
- functions:
+
+
+ If you want to exute Stored Functions instead, the following
+ databases are fully supported:
+
MySQL
Microsoft SQL Server
Oracle
PostgreSQL
-
-
- Even though your particular database may not be fully supported, chances
- are that you can use the Stored Procedures Spring Integration
- components quite successfully anyway, provided your RDBMS supports
- Stored Procedures or Functions.
- As a matter of fact, some of the provided
- integration tests use the the H2 database. Nevertheless it is very important
- to thouroughly test those usasge scenarios.
+
+
+
+
+ Even though your particular database may not be fully supported,
+ chances are, that you can use the Stored Procedure Spring Integration
+ components quite successfully anyway, provided your RDBMS supports
+ Stored Procedures or Functions.
+
+ As a matter of fact, some of the provided integration tests use
+ the H2 database.
+ Nevertheless, it is very important to thoroughly test those usage scenarios.
+
+
+
+ Configuration
+
+ The Stored Procedure components provide full XML Namespace support
+ and configuring the components is similar as for the general purpose
+ JDBC components discussed earlier.
+
+
+
+
+ Common Configuration Attributes
+
+ Certain configuration parameters are shared among all Stored Procedure
+ components and are described below:
+
+
+ auto-startup
+
+ Lifecycle attribute signaling if this component should
+ be started during Application Context startup.
+ Defaults to true.
+ Optional.
+
+
+ data-source
+
+ Reference to a javax.sql.DataSource,
+ which is used to access the database.
+ Required.
+
+
+ id
+
+ Identifies the underlying Spring bean definition, which
+ is an instance of either EventDrivenConsumer
+ or PollingConsumer, depending
+ on whether the Outbound Channel Adapter's channel
+ attribute references a SubscribableChannel
+ or a PollableChannel.
+ Optional.
+
+
+ ignore-column-meta-data
+
+ For fully supported databases, the underlying
+ SimpleJdbcCall
+ class can automatically retrieve the parameter information
+ for the to be invoked Stored Procedure or Function
+ from the JDBC Meta-data.
+
+
+ However, if the used database does not support meta
+ data lookups or if you like to provide customized parameter
+ definitions, this flag can be set to true. It defaults
+ to false.
+ Optional.
+
+
+ is-function
+
+ If true, a SQL Function is called. In that case the
+ stored-procedure-name attribute defines the name of
+ the called function. Defaults to false.
+ Optional.
+
+ stored-procedure-name
+
+ The attribute specifies the name of the stored procedure. If the
+ is-function attribute is set to true,
+ this attribute specifies the function name.
+ Required.
+
+ sql-parameter-source-factory
+
+ Reference to a SqlParameterSourceFactory.
+
+ By default bean properties of the passed in
+ Message payload will be used
+ as a source for the Stored Procedure's input parameters
+ using a BeanPropertySqlParameterSourceFactory.
+
+
+ This may be sufficient for basic use cases. For more
+ sophisticated options, consider passing in one or more
+ ProcedureParameter. Please also refer to
+
+ Optional.
+
+
+
+
+ Common Configuration Sub-Elements
+
+ The Stored Procedure components share a common set of sub-elements
+ to define and pass parameters to Stored Procedures or Functions.
+ The following elements are available:
+
+
+
+ parameter
+ returning-resultset
+ sql-parameter-definition
+ poller
+
+
+ parameter
+
+ Provides a mechanism to provide Stored Procedure parameters.
+ Parameters can be either static or provided using a SpEL Expressions.
+ Optional.
+
+
+ ]]>]]>
+
+
+
+
+
+ The name of the parameter to be passed into the
+ Stored Procedure or Stored Function.
+ Required.
+
+
+
+
+ This attribute specifies the type of the value. If
+ nothing is provided this attribute will default to
+ java.lang.String. This attribute
+ is only used when the value attribute is
+ used.
+ Optional.
+
+
+
+
+ The value of the parameter. You have to provider either
+ this attribute or the expression attribute must be
+ provided instead.
+ Optional.
+
+
+
+
+ Instead of the value attribute, you can
+ also specify a SpEL expression for passing the value
+ of the parameter. If you specify the expression
+ the value attribute is not allowed.
+ Optional.
+
+
+
+
+
+ returning-resultset
+
+ Stored Procedures may return multiple resultsets. By setting one
+ or more returning-resultset elements, you can specify
+ RowMappers in order to convert
+ each returned ResultSet to meaningful objects.
+ Optional.
+
+ ]]>
+
+ sql-parameter-definition
+
+
+ If you are using a database that is fully supported, you typically
+ don't have to specify the Stored Procedure parameter definitions.
+ Instead, those parameters can be automatically derived from the
+ JDBC Meta-data. However, if you are using databases that are not
+ fully support, you must set those parameters explicitly using the
+ sql-parameter-definition sub-element.
+
+
+ You can also choose to turn off any processing of parameter meta
+ data information obtained via JDBC using the ignore-column-meta-data
+ attribute.
+
+
+ ]]>
+
+
+
+
+ Specifies the name of the SQL parameter.
+ Required.
+
+
+
+
+ Specifies the direction of the SQL parameter definition.
+ Defaults to IN. Valid values are:
+ IN,
+ OUT and
+ INOUT.
+ If your procedure is returning ResultSets,
+ please use the returning-resultset element.
+ Optional.
+
+
+
+
+ The SQL type used for this SQL parameter definition. Will translate
+ into the integer value as defined by java.sql.Types. Alternatively
+ you can provide the integer value as well. If this attribute is
+ not explicitly set, then it will default to 'VARCHAR'.
+ Optional.
+
+
+
+
+ The scale of the SQL parameter. Only used for numeric and decimal
+ parameters.
+ Optional.
+
+
+
+
+
+ poller
+
+ Allows you to configure Message Poller if this endpoint is a
+ PollingConsumer
+ Optional.
+
+
+
+
Defining Parameter Sources
- TBD
-
-
- Stored Procedures Inbound Channel Adapter
-
-
-
+ Parameter Sources govern the techniques of retrieving and mapping the
+ Spring Integration Message properties to the relevant Stored Procedure
+ input parameters. The Stored Procedure components follow certain rules.
+
+
+ By default bean properties of the passed in
+ Message payload will be used as a
+ source for the Stored Procedure's input parameters. In that case a
+ BeanPropertySqlParameterSourceFactory will
+ be used. This may be sufficient for basic use cases. The following
+ example illustrates that default behavior.
+
+
+ Please be aware that for the "automatic" lookup of bean properties
+ using the BeanPropertySqlParameterSourceFactory
+ to work, your bean properties must be defined in lower case.
+ This is due to the fact that in
+ org.springframework.jdbc.core.metadata.CallMetaDataContext
+ (method matchInParameterValuesWithCallParameters()), the retrieved
+ Stored Procedure parameter declarations are converted to lower case.
+
+ As a result, if you have camel-case bean properties such as "lastName",
+ the lookup will fail. In that case, please provide an explicit
+ ProcedureParameter.
+
+
+ Let's assume we have a payload that consists of a simple bean with
+ the following three properties: id,
+ name and description.
+ Furthermore, we have a simplistic Stored Procedure called INSERT_COFFEE
+ that accepts three input parameters:
+ id,
+ name and
+ description. We also use a fully supported
+ database. In that case the following configuration for an Stored
+ Procedure Oubound Adapter will be sufficient:
+
+ ]]>
+
+ For more sophisticated options consider passing in one or more
+ ProcedureParameter.
+
+
+ If you do provide ProcedureParameter explicitly,
+ then as default an ExpressionEvaluatingSqlParameterSourceFactory
+ will be used for parameter processing in order to enable the full
+ power of SpEL expressions.
+
+
+ Furthermore, if you need even more control over how parameters are
+ retrieved, consider passing in a custom implementation of a
+ SqlParameterSourceFactory using the
+ sql-parameter-source-factory attribute.
+
+
+
+ Stored Procedure Inbound Channel Adapter
+
+ ]]> ]]> ]]> ]]> ]]> ]]> ]]>
-
+ stored-procedure-name=""
+ data-source=""
+ auto-startup="true"
+ id=""
+ ignore-column-meta-data="false"
+ is-function="false"
+ max-rows-per-poll="" ]]>
+
+
+
+
+]]>
- Channel to which polled messages will be send. If the stored
+
+ Channel to which polled messages will be sent. If the stored
procedure or function does not return any data, the payload
- of the Message will be Null. Required.
+ of the Message will be Null.
+ Required.
+
- The name of the stored procedure. If the "is-function"
- attribute is "true", this attributes specifies the
- function name. Required.
+
+ Limits the number of rows extracted per query. Otherwise
+ all rows are extracted into the outgoing message.
+ Optional.
+
- Reference to a data source to use to access
- the database. Required.
+
+ If this attribute is set to true, then
+ all results from a stored procedure call that don't
+ have a corresponding SqlOutParameter
+ declaration will be bypassed.
+
+
+ E.g. Stored Procedures may return an update count value,
+ even though your Stored Procedure only declared a single
+ result parameter. The exact behavior depends on the used
+ database. The value is set on the underlying
+ JdbcTemplate.
+
+
+ Only few developers will probably ever like to process
+ update counts, thus the value defaults to true.
+ Optional.
+
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- If "true", a SQL Function is called. In that case
- the "stored-procedure-name" attribute defines
- the name of the called function. Defaults to false. Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Specifies the direction of the Sql parameter definition.
- Defaults to 'IN'. If your procedure is returning ResultSets,
- please use the 'returning-resultset' element. Optional.
-
-
- The Sql type used for this Sql parameter defintion. Will translate
- into the integer value as defined by java.sql.Types. Alternatively
- you can provide the integer value as well. If this attribute is
- not explicitly set, then it will default to 'VARCHAR'.Optional.
-
-
- The scale of the Sql parameter. Only used for numeric and decimal
- parameters. Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
+
-
- Stored Procedures Outbound Channel Adapter
-
-
- ]]>
+ Stored Procedure Outbound Channel Adapter
+
+
-
-
- ]]>
-
+
+]]>
- Required.
+
+ The receiving Message Channel of this endpoint.
+ Required.
+
- The name of the stored procedure. If the "is-function"
- attribute is "true", this attributes specifies the
- function name. Required.
+
+ Specifies the order for invocation when this endpoint
+ is connected as a subscriber to a channel. This is
+ particularly relevant when that channel is using a
+ failover dispatching strategy.
+ It has no effect, when this endpoint itself is a
+ Polling Consumer for a channel with a queue.
+ Optional.
+
- Reference to a data source to use to access
- the database. Required.
+
+ Indicates whether this procedure's return value
+ should be included.
+ Optional.
+
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
+
-
- Stored Procedures Outbound Gateway
+
+ Stored Procedure Outbound Gateway
+
+
+
+
+
+
+]]>
-
- ]]> ]]> ]]> ]]> ]]> ]]>
-
- Required.
+
+ The receiving Message Channel of this endpoint.
+ Required.
+
- The name of the stored procedure. If the "is-function"
- attribute is "true", this attributes specifies the
- function name. Required.
+
+ Message Channel to which replies should be sent,
+ after receiving the database response.
+ Optional.
+
- Reference to a data source to use to access
- the database. Required.
+
+ Allows you to specify how long this gateway will wait
+ for the reply message to be sent successfully before
+ throwing an exception. Keep in mind that when sending
+ to a DirectChannel (The invocation
+ will occur in the sender's thread.) the failing of the
+ send operation may be caused by other components further
+ downstream.
+
+ By default the Gateway will wait indefinitely. The
+ value is specified in milliseconds.
+ Optional.
+
- Optional.
+
+ Indicates whether this procedure's return value
+ should be included.
+ Optional.
+
-
- Optional.
-
-
- Optional.
-
-
- If "true", a SQL Function is called. In that case
- the "stored-procedure-name" attribute defines
- the name of the called function. Defaults to false. Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
- Optional.
-
-
-
+
+
+ If the skip-undeclared-results attribute
+ is set to true, then all results from
+ a stored procedure call that don't have a
+ corresponding SqlOutParameter
+ declaration will be bypassed.
+
+
+ E.g. Stored Procedures may return an update count value,
+ even though your Stored Procedure only declared a single
+ result parameter. The exact behavior depends on the used
+ database. The value is set on the underlying
+ JdbcTemplate.
+
+
+ Only few developers will probably ever like to process
+ update counts, thus the value defaults to true.
+ Optional.
+
+
+
+
+
+
+ Examples
+
+ In the following two examples we call Apache Derby
+ Stored Procedures. The first procedure will call a Stored Procedure that
+ returns a ResultSet, and using a RowMapper
+ the data is converted into a domain object, which then becomes the
+ Spring Integration message payload.
+
+
+ In the second sample we call a Stored Procedure that uses
+ Output Parameters instead, in order to return data.
+
+
+
+ Please have a look at the Spring Integration Samples
+ project, located at
+
+
+
+ The project contains the Apache Derby example referenced
+ here, as well as instruction on how to run it. The
+ Spring Integration Samples project also
+ provides an
+ example
+ using Oracle Stored Procedures.
+
+
+
+ In the first example, we call a Stored Procedure named
+ FIND_ALL_COFFEE_BEVERAGES that does not
+ define any input parameters but which returns a ResultSet.
+
+
+ In Apache Derby, Stored Procedures are implemented using Java. Here
+ is the method signature followed by the corresponding Sql:
+
+
+
+
+
+
+ In Spring Integration, you can now call this Stored Procedure using
+ e.g. a stored-proc-outbound-gateway
+
+
+
+ ]]>
+
+
+ In the second example, we call a Stored Procedure named
+ FIND_COFFEE that has one input parameter. Instead
+ of returning a ResultSet, an output parameter is used:
+
+
+
+
+
+
+
+ In Spring Integration, you can now call this Stored Procedure using
+ e.g. a stored-proc-outbound-gateway
+
+
+
+]]>
+
+
diff --git a/spring-integration-jdbc/src/main/resources/org/springframework/integration/jdbc/config/spring-integration-jdbc-2.1.xsd b/spring-integration-jdbc/src/main/resources/org/springframework/integration/jdbc/config/spring-integration-jdbc-2.1.xsd
index 9b54ee1497..fb35a35a07 100644
--- a/spring-integration-jdbc/src/main/resources/org/springframework/integration/jdbc/config/spring-integration-jdbc-2.1.xsd
+++ b/spring-integration-jdbc/src/main/resources/org/springframework/integration/jdbc/config/spring-integration-jdbc-2.1.xsd
@@ -395,6 +395,9 @@
+
+ The receiving Message Channel of this endpoint.
+
@@ -404,6 +407,10 @@
+
+ Message Channel to which replies should be sent,
+ after receiving the database response.
+
@@ -675,10 +682,10 @@
-
-
-
-
+
+ Indicates whether this procedure's return value
+ should be included.
+
@@ -869,6 +876,9 @@
+
+ The receiving Message Channel of this endpoint.
+
+
+ Message Channel to which replies should be sent,
+ after receiving the database response.
+
-
+
+
+
+ Identifies the underlying Spring bean definition, which is an
+ instance of either 'EventDrivenConsumer' or 'PollingConsumer',
+ depending on whether the component's input channel is a
+ 'SubscribableChannel' or 'PollableChannel'.
+
+
+