diff --git a/src/reference/docbook/jdbc.xml b/src/reference/docbook/jdbc.xml index aa2b0966c3..85491351bc 100644 --- a/src/reference/docbook/jdbc.xml +++ b/src/reference/docbook/jdbc.xml @@ -5,8 +5,8 @@ Spring Integration provides Channel Adapters for receiving and sending - messages via database queries. Through those adapters Spring Integration - supports not only plain JDBC SQL Queries, but also Stored Procedure and + messages via database queries. Through those adapters Spring Integration + supports not only plain JDBC SQL Queries, but also Stored Procedure and Stored Function calls. @@ -33,7 +33,7 @@ - Furthermore, the Spring Integration JDBC Module also provides a + Furthermore, the Spring Integration JDBC Module also provides a JDBC Message Store @@ -115,63 +115,63 @@ payload and headers are available by default as input parameters to the query, for instance: - + ]]> - In the example above, messages arriving on the channel labelled - input have a payload of a map with key - foo, so the [] operator dereferences + In the example above, messages arriving on the channel labelled + input have a payload of a map with key + foo, so the [] operator dereferences that value from the map. The headers are also accessed as a map. - + - The parameters in the query above are bean property expressions on the + The parameters in the query above are bean property expressions on the incoming message (not Spring EL expressions). This behavior is part of the SqlParameterSource - which is the default source created by the outbound adapter. Other - behavior is possible in the adapter, and requires the user to inject a + which is the default source created by the outbound adapter. Other + behavior is possible in the adapter, and requires the user to inject a different SqlParameterSourceFactory. - The outbound adapter requires a reference to either a - DataSource or a - JdbcTemplate. It can also have a - SqlParameterSourceFactory injected to control + The outbound adapter requires a reference to either a + DataSource or a + JdbcTemplate. It can also have a + SqlParameterSourceFactory injected to control the binding of each incoming message to a query. - If the input channel is a direct channel, then the outbound adapter runs + If the input channel is a direct channel, then the outbound adapter runs its query in the same thread, and therefore the same transaction (if there is one) as the sender of the message. - + Passing Parameters using SpEL Expressions A common requirement for most JDBC Channel Adapters is to pass parameters as part of Sql queries or Stored Procedures/Functions. As mentioned above, - these parameters are by default bean property expressions, not SpEL expressions. - - However, if you need to pass SpEL expression as parameters, you must inject + these parameters are by default bean property expressions, not SpEL expressions. + + However, if you need to pass SpEL expression as parameters, you must inject a SqlParameterSourceFactory explicitly. - The following example uses a ExpressionEvaluatingSqlParameterSourceFactory - to achieve that requirement. + The following example uses a ExpressionEvaluatingSqlParameterSourceFactory + to achieve that requirement. - + - - @@ -182,7 +182,7 @@ ]]> - For further information, please also see + For further information, please also see @@ -300,7 +300,7 @@ logical name. - +
Stored Procedures @@ -309,7 +309,7 @@ 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 + three components in order to execute Stored Procedures or Stored Functions: @@ -317,7 +317,7 @@ Stored Procedures Outbound Channel Adapter Stored Procedures Outbound Gateway - +
Supported Databases @@ -355,7 +355,7 @@ Stored Procedures or Functions. As a matter of fact, some of the provided integration tests use - the H2 database. + the H2 database. Nevertheless, it is very important to thoroughly test those usage scenarios. @@ -367,7 +367,7 @@ JDBC components discussed earlier.
- +
Common Configuration Attributes @@ -385,7 +385,7 @@ data-source - Reference to a javax.sql.DataSource, + Reference to a javax.sql.DataSource, which is used to access the database. Required. @@ -418,19 +418,59 @@ 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. - + + If true, a SQL Function is called. In that case the + stored-procedure-name or + stored-procedure-name-expression attributes define + 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. - + + The attribute specifies the name of the stored procedure. If the + is-function attribute is set to true, + this attribute specifies the function name instead. Either this + property or stored-procedure-name-expression + must be specified. + + stored-procedure-name-expression + + This attribute specifies the name of the stored procedure using + a SpEL expression. Using SpEL you have access to the full message + (if available), including its headers and payload. You can use + this attribute to invoke different Stored Procedures at runtime. + For example, you can provide Stored Procedure names that you would + like to execute as a Message Header. The expression must resolve + to a String. + + + If the is-function attribute is set to true, + this attribute specifies a Stored Function. Either this property + or stored-procedure-name must be specified. + + jdbc-call-operations-cache-size + + Defines the maximum number of cached + SimpleJdbcCallOperations instances. + Basically, for each Stored Procedure Name a new + SimpleJdbcCallOperations + instance is created that in return is being cached. + + + The stored-procedure-name-expression attribute + and the jdbc-call-operations-cache-size + were added with Spring Integration 2.2. + + + The default cache size is 10. + A value of 0 disables caching. + Negative values are not permitted. + + + If you enable JMX, statistical information about the + jdbc-call-operations-cache is exposed as MBean. Please + see for more information. + sql-parameter-source-factory (Not available for the Stored Procedure Inbound Channel Adapter.) @@ -445,39 +485,39 @@ This may be sufficient for basic use cases. For more sophisticated options, consider passing in one or more - ProcedureParameter. Please also refer to + ProcedureParameter. Please also refer to . Optional. - - use-payload-as-parameter-source + + use-payload-as-parameter-source (Not available for the Stored Procedure Inbound Channel Adapter.) - + - If set to true, the payload of the Message - will be used as a source for providing parameters. - If false, however, the entire Message will be available as a + If set to true, the payload of the Message + will be used as a source for providing parameters. + If false, however, the entire Message will be available as a source for parameters. - + If no Procedure Parameters are passed in, this property - will default to true. This means that using a default - BeanPropertySqlParameterSourceFactory - the bean properties of the payload will be used as a - source for parameter values for the to-be-executed + will default to true. This means that using a default + BeanPropertySqlParameterSourceFactory + the bean properties of the payload will be used as a + source for parameter values for the to-be-executed Stored Procedure or Stored Function. - - However, if Procedure Parameters are passed in, then - this property will by default evaluate to false. - ProcedureParameter allow for - SpEL Expressions to be provided and therefore it is + + However, if Procedure Parameters are passed in, then + this property will by default evaluate to false. + ProcedureParameter allow for + SpEL Expressions to be provided and therefore it is highly beneficial to have access to the entire Message. The property is set on the underlying StoredProcExecutor. Optional. - +
- +
Common Configuration Sub-Elements @@ -590,7 +630,7 @@ Defaults to IN. Valid values are: IN, OUT and - INOUT. + INOUT. If your procedure is returning ResultSets, please use the returning-resultset element. Optional. @@ -632,55 +672,55 @@ input parameters. The Stored Procedure components follow certain rules. - By default bean properties of the passed in - Message payload will be used as a + 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 + 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 + 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 + + 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. + the following three properties: id, + name and description. Furthermore, we have a simplistic Stored Procedure called INSERT_COFFEE - that accepts three input parameters: + that accepts three input parameters: id, name and - description. We also use a fully supported + description. We also use a fully supported database. In that case the following configuration for a Stored - Procedure Oubound Adapter will be sufficient: + Procedure Oubound Adapter will be sufficient: ]]> - - For more sophisticated options consider passing in one or more + channel="insertCoffeeProcedureRequestChannel" + stored-procedure-name="INSERT_COFFEE"/>]]> + + For more sophisticated options consider passing in one or more ProcedureParameter. - - If you do provide ProcedureParameter explicitly, + + 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 + retrieved, consider passing in a custom implementation of a + SqlParameterSourceFactory using the sql-parameter-source-factory attribute.
@@ -724,19 +764,19 @@ - If this attribute is set to true, then - all results from a stored procedure call that don't - have a corresponding SqlOutParameter + 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 + database. The value is set on the underlying JdbcTemplate. - + Few developers will probably ever want to process update counts, thus the value defaults to true. Optional. @@ -748,15 +788,15 @@ Stored Procedure Outbound Channel Adapter + use-payload-as-parameter-source=""> @@ -794,19 +834,19 @@ Stored Procedure Outbound Gateway + use-payload-as-parameter-source=""> @@ -832,15 +872,15 @@ - 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 so the failing of the + 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 so the failing of the send operation may be caused by other components further - downstream. - - By default the Gateway will wait indefinitely. The + downstream. + + By default the Gateway will wait indefinitely. The value is specified in milliseconds. Optional. @@ -854,25 +894,25 @@ - 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 + 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 + database. The value is set on the underlying JdbcTemplate. - + Few developers will probably ever want to process update counts, thus the value defaults to true. Optional. - +
@@ -886,33 +926,33 @@ Spring Integration message payload. - In the second sample we call a Stored Procedure that uses + 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 + 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 + 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 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 + 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 + 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 + 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 + In Spring Integration, you can now call this Stored Procedure using e.g. a stored-proc-outbound-gateway - - + ]]> - + diff --git a/src/reference/docbook/whats-new.xml b/src/reference/docbook/whats-new.xml index a35ae01fa7..9b2919fdba 100644 --- a/src/reference/docbook/whats-new.xml +++ b/src/reference/docbook/whats-new.xml @@ -32,6 +32,31 @@ Support for Dead Letter Exchanges/Dead Letter Queues +
+ JDBC Adapter - Stored Procedures Components + SpEL Support + + When using the Stored Procedure components of the Spring Integration + JDBC Adapter, you can now provide Stored Procedure Names or + Stored Function Names using Spring Expression Language (SpEL). + + + This allows you to specify the Stored Procedures to be invoked + at runtime. For example, you can provide Stored Procedure names + that you would like to execute via Message Headers. For more + information please see . + + JMX Support + + The Stored Procedure components now provide basic JMX support, + exposing some of their properties as MBeans: + + + Stored Procedure Name + Stored Procedure Name Expression + JdbcCallOperations Cache Statistics + +