From d1c740930ce59af05ea9611e5f997795fba488ef Mon Sep 17 00:00:00 2001 From: Gunnar Hillert Date: Wed, 16 Nov 2011 14:03:05 -0500 Subject: [PATCH] INT-2175 - Add Doc for Stored Proc Components For reference see: https://jira.springsource.org/browse/INT-2175 --- docs/src/reference/docbook/jdbc.xml | 817 +++++++++++++----- .../config/spring-integration-jdbc-2.1.xsd | 33 +- 2 files changed, 610 insertions(+), 240 deletions(-) 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'. + + +