diff --git a/src/reference/docbook/jpa.xml b/src/reference/docbook/jpa.xml index 0cc3e8498a..f193e8d1cc 100644 --- a/src/reference/docbook/jpa.xml +++ b/src/reference/docbook/jpa.xml @@ -8,15 +8,18 @@ components are provided: - - Outbound Channel adapter - - - Outbound Gateway - Inbound Channel Adapter + + Outbound Channel Adapter + + + Updating Outbound Gateway + + + Retrieving Outbound Gateway + These components can be used to perform @@ -24,11 +27,41 @@ create, update and delete - operations on the targeted database by sending/receiving messages to them. + operations on the targeted databases by sending/receiving messages to them. - The above operations can be performed using either of the - following: + The JPA Inbound Channel Adapter lets you poll and + retrieve (select) data from the database using JPA whereas the JPA + Outbound Channel Adapter lets you create, update + and delete entities. + + + Outbound Gateways for JPA can be used to persist entities to the + database, yet allowing you to continue with the flow and execute further + components downstream. Similarly, you can use an Outbound Gateway to retrieve + entities from the database. + + + For example, you may use the Outbound Gateway, which receives a Message + with a user Id as payload on its request channel, to query the database + and retrieve the User entity and pass it downstream for further processing. + + + Recognizing these semantic differences, Spring Integration provides 2 separate + JPA Outbound Gateways: + + + + Retrieving Outbound Gateway + + + Updating Outbound Gateway + + + Functionality + + All JPA components perform their respective JPA operations by using + either one of the following: @@ -43,10 +76,10 @@ - Native query + Native Query - Named query + Named Query @@ -71,21 +104,25 @@ EclipseLink + + When using a persistence provider, please ensure that the provider + is compatible with JPA 2.0. +
Java Implementation Each of the provided components will use the - org.springframework.integration.jpa.core.JpaExecutor + o.s.i.jpa.core.JpaExecutor class which in turn will use an implementation of the - org.springframework.integration.jpa.core.JpaOperations + o.s.i.jpa.core.JpaOperations interface. JpaOperations operates like a typical Data Access Object (DAO) and provides methods such as find, persist, executeUpdate etc. For most use cases the provided default implementation - org.springframework.integration.jpa.core.DefaultJpaOperations - should be sufficient. Nevertheless, the provided components allow you to + o.s.i.jpa.core.DefaultJpaOperations + should be sufficient. Nevertheless, you have the option to optionally specify your own implementation in case you require custom behavior. @@ -105,20 +142,30 @@ JpaOperations - Example + + The XML Namespace Support described further below is also very + flexible and provides configuration attributes for + each JPA component to pass in an EntityManagerFactory, + EntityManager or JpaOperations + reference. + + Java Configuration Example - The following example of a JPA Outbound Gateway is configured purely - through Java. In typical usage scenarios you will most likely prefer + The following example of a JPA Retrieving Outbound Gateway is configured + purely through Java. In typical usage scenarios you will most likely prefer the XML Namespace Support described further below. However, the example - illustrates how the classes are wired up. + illustrates how the classes are wired up. Understanding the inner + workings can also be very helpful for debugging or customizing + the individual JPA components. + First, we instantiate a JpaExecutor using an EntityManager as constructor argument. - The JpaExecutor is then used as constructor argument for the - o.s.i.jpa.outbound.JpaOutboundGateway and the - JpaOutboundGateway will be passed as constructor - argument in to the EventDrivenConsumer. + The JpaExecutor is then in return used as + constructor argument for the o.s.i.jpa.outbound.JpaOutboundGateway + and the JpaOutboundGateway will be passed as constructor + argument into the EventDrivenConsumer. @@ -147,153 +194,160 @@ ]]> - - - When using XML Namespace Support the underlying parser classes will - instantiate the classes for you. Thus, you typically don't have to - deal with the inner workings but in case you need to debug the JPA - Components of your message flow, or if you need to provide customization - understanding it will be helpful. The following section will describe - how to use the XML Namespace Support to configure the Jpa components. - -
-
- Common Configuration Attributes - - Certain configuration parameters are shared amongst all JPA components and are described below: - - - auto-startup - - Lifecycle attribute signaling if this component should - be started during Application Context startup. - Defaults to true. - Optional. - - - id - - Identifies the underlying Spring bean definition, which - is an instance of either EventDrivenConsumer - or PollingConsumer. - Optional. - - - entity-manager-factory - - The reference to the JPA Entity Manager Factory - that will be used by the adapter to create the EntityManager. - Either this attribute or the enity-manager attribute - or the jpa-operations attribute must be provided. - - - entity-manager - - The reference to the JPA Entity Manager that will be used by - the component. - Either this attribute or the enity-manager-factory attribute - or the jpa-operations attribute must be provided. - - Usually your Spring Application Context only defines a - JPA Entity Manager Factory and the EntityManager is injected using - the @PersistenceContext annotation. This, however, is not applicable for - the Spring Integration JPA components. - - Usually, injecting the JPA Entity Manager Factory will be best but in - case you want to inject an EntityManager explicitly, you have to define - a SharedEntityManagerBean. For more information, - please see the relevant - JavaDoc. + For more examples of constructing JPA components purely through Java, + see the JUnit test-cases for the JPA Adapters. - +
+ Namespace Support + + When using XML namespace support, the underlying parser classes will + instantiate the relevant Java classes for you. Thus, you typically don't have to + deal with the inner workings of the JPA adapter. This section will + document the XML Namespace Support provided by the Spring Integration + and will show you how to use the XML Namespace Support to configure + the Jpa components. + +
+ Common XML Namespace Configuration Attributes + + Certain configuration parameters are shared amongst all JPA components and are described below: + + + auto-startup + + Lifecycle attribute signaling if this component should + be started during Application Context startup. + Defaults to true. + Optional. + + + id + + Identifies the underlying Spring bean definition, which + is an instance of either EventDrivenConsumer + or PollingConsumer. + Optional. + + + entity-manager-factory + + The reference to the JPA Entity Manager Factory + that will be used by the adapter to create the EntityManager. + Either this attribute or the entity-manager attribute + or the jpa-operations attribute must be provided. + + + entity-manager + + The reference to the JPA Entity Manager that will be used by + the component. + Either this attribute or the enity-manager-factory attribute + or the jpa-operations attribute must be provided. + + + Usually your Spring Application Context only defines a + JPA Entity Manager Factory and the EntityManager is injected using + the @PersistenceContext annotation. This, however, is not applicable for + the Spring Integration JPA components. + + Usually, injecting the JPA Entity Manager Factory will be best but in + case you want to inject an EntityManager explicitly, you have to define + a SharedEntityManagerBean. For more information, + please see the relevant + JavaDoc. + + ]]> - jpa-operations - - Reference to a bean implementing the - JpaOperations interface. In rare cases - it might be advisable to provide your own implementation - of the JpaOperations interface, instead - of relying on the default implementation - org.springframework.integration.jpa.core.DefaultJpaOperations. - As JpaOperations wraps the necessary - datasource; the JPA Entity Manager or JPA Entity Manager Factory - must not be provided, if the jpa-operations - attribute is used. - + jpa-operations + + Reference to a bean implementing the + JpaOperations interface. In rare cases + it might be advisable to provide your own implementation + of the JpaOperations interface, instead + of relying on the default implementation + org.springframework.integration.jpa.core.DefaultJpaOperations. + As JpaOperations wraps the necessary + datasource; the JPA Entity Manager or JPA Entity Manager Factory + must not be provided, if the jpa-operations + attribute is used. + - entity-class - - The reference to the JPA Persistence Entity. The exact semantics of - this attribute vary, depending on whether we are performing a persist/update - operation or whether we are retrieving objects from the database. - - - When retrieving data, you can specify the - entity-class attribute to indicate that you would - like to retrieve objects of this type from the database. In that case - you must not define any of the query attributes ( - jpa-query, - native-query or - named-query - ) - - - When persisting data, the entity-class attribute - will indicate the type of object to persist. If not specified - (for persist operations) the entity class will be automatically retrieved - from the Message's payload. - + entity-class + + The fully qualified name of the entity class. The exact semantics of + this attribute vary, depending on whether we are performing a persist/update + operation or whether we are retrieving objects from the database. + + + When retrieving data, you can specify the + entity-class attribute to indicate that you would + like to retrieve objects of this type from the database. In that case + you must not define any of the query attributes ( + jpa-query, + native-query or + named-query + ) + + + When persisting data, the entity-class attribute + will indicate the type of object to persist. If not specified + (for persist operations) the entity class will be automatically retrieved + from the Message's payload. + - jpa-query - - Defines the JPA query (Java Persistence Query Language) to be used. - + jpa-query + + Defines the JPA query (Java Persistence Query Language) to be used. + - native-query - - Defines the native SQL query to be used. - + native-query + + Defines the native SQL query to be used. + - named-query - - This attribute refers to a named query. A named query can - either be defined in Native SQL or JPAQL but the underlying JPA - persistence provider handles that distinction internally. - + named-query + + This attribute refers to a named query. A named query can + either be defined in Native SQL or JPAQL but the underlying JPA + persistence provider handles that distinction internally. + -
+
-
- Providing JPA Query Parameters - - For providing parameters, the JPA Parameter XML sub-element can be used. - It provides a mechanism to provide parameters for the queries that are - either based on the Java Persistence Query Language (JPQL) or native SQL - queries. Parameters can also be provided for Named Queries. - +
+ Providing JPA Query Parameters + + For providing parameters, the parameter XML + sub-element can be used. It provides a mechanism to provide + parameters for the queries that are either based on the Java + Persistence Query Language (JPQL) or native SQL queries. Parameters + can also be provided for Named Queries. + - Expression based Parameters - ]]> + Expression based Parameters + ]]> - Value based Parameters - ]]> + Value based Parameters + ]]> - Positional Parameters - + Positional Parameters + ]]> -
+
-
- Transaction Handling - - All JPA operations like Insert, Update and Delete require a transaction to be active whenever they are - performed. For inbound channel adapters there is nothing special to be done, it is similar - to the way we configure transaction managers with pollers used with other inbound channel - adapters.The xml snippet below shows a sample where a transaction manager is configured with - the poller used with an inbound channel adapter. +
+ Transaction Handling + + All JPA operations like Insert, Update and Delete require a transaction to be active whenever they are + performed. For Inbound Channel Adapters there is nothing special to be done, it is similar + to the way we configure transaction managers with pollers used with other inbound channel + adapters.The xml snippet below shows a sample where a transaction manager is configured with + the poller used with an Inbound Channel Adapter. + - ]]> - - However, it may be necessary to specifically start a transaction when using an outbound channel adapter/gateway. - If a DirectChannel is an input channel for the outbound adapter/gateway, - and if transaction is active in the current thread of execution, the JPA operation will be - performed in the same transaction context. We can also configure to execute this JPA operation - in a new transaction as below. + ]]> + + However, it may be necessary to specifically start a transaction when using an Outbound Channel Adapter/Gateway. + If a DirectChannel is an input channel for the outbound adapter/gateway, + and if transaction is active in the current thread of execution, the JPA operation will be + performed in the same transaction context. We can also configure to execute this JPA operation + in a new transaction as below. + ]]> ]]> - - As we can see above, the transactional sub element of the outbound gateway/adapter will be - used to specify the transaction attributes. It is optional to define this child element if - you have DirectChannel as an input channel to the adapter and you want the - adapter to execute the operations in the same transaction context as the caller. - If, however, you are using an ExecutorChannel, it is required to have the - transactional sub element as the invoking client's transaction context is not - propagated. - - Unlike the transactional sub element of the poller which is defined - in the spring integration's namespace, the transactional sub element for the - outbound gateway/adapter is defined in the jpa namespace. - -
- -
- Outbound Channel Adapter - - The JPA Outbound channel adapter allows you to accept messages via a - request channel. The payload can either be used as the entity to be persisted, - or used along with the headers in parameter expressions for a defined JPQL query to be executed. - - In the following sub sections we shall see what those possible ways of performing - these operations are. - -
- Using an Entity Class +]]> - The XML snippet below shows how we can use the Outbound Channel - Adapter to persist an entity to the database. + As we can see above, the transactional sub element of the outbound gateway/adapter will be + used to specify the transaction attributes. It is optional to define this child element if + you have DirectChannel as an input channel to the adapter and you want the + adapter to execute the operations in the same transaction context as the caller. + If, however, you are using an ExecutorChannel, it is required to have the + transactional sub element as the invoking client's transaction context is not + propagated. - ]]> + Unlike the transactional sub element of the poller which is defined + in the spring integration's namespace, the transactional sub element for the + outbound gateway/adapter is defined in the jpa namespace. + +
+
+
+ Inbound Channel Adapter + + An Inbound Channel Adapter is used to execute a select query over the + database using JPA QL and return the result. The message payload will be either a single + entity or a List of entities. Below is a sample xml snippet that shows + a sample usage of inbound-channel-adapter. + + ]]> + + +]]> + + + + + The channel over which the inbound-channel-adapter will put the + messages with the payload received after executing the provided JPA QL in the + query attribute. + + + + + The EntityManager instance that will be used to perform the + required JPA operations. + + + + + Attribute signalling if the component should be automatically started on startup of + the Application Context. The value defaults to true + + + + + The JPA QL that needs to be executed and whose result needs to be sent out as the + payload of the message + + + + + The attribute that tells if the executed JPQL query gives a single entity in the result + or a List of entities. If the value is set to true, + the single entity retrieved is sent as the payload of the message. If, however, multiple + results are returned after setting this to true, a + MessagingException is thrown. The value defaults to false. + + + + + Set this value to true if you want + to delete the rows received after execution of the query. + Please ensure that the component is operating as part + of a transaction. + + Otherwise, you may encounter an Exception such as: + java.lang.IllegalArgumentException: Removing + a detached instance ... + + + +
+ Configuration Parameter Reference + + + ]]> - + - The channel over which a valid JPA entity will be - sent to the JPA Outbound Channel Adapter. + This Lifecycle attribute signaled if this component should be started during startup of the Application Context. + This attribute defaults to true.Optional. - + - The fully qualified name of the entity class that - would be accepted by the adapter to be persisted - in the database. You can actually leave off this - attribute in most cases as the adapter can determine - the entity class automatically from the Spring Integration - Message payload. + The channel to which the adapter will send a message with the payload that was received after + performing the desired JPA operation. - + - The operation that needs to be done by the adapter, valid values are - PERSIST, MERGE - and DELETE. The default value - is MERGE. + A boolean flag that indicates whether the records selected are to be deleted + after they are being polled by the adapter. By default the value is false, + that is, the records will not be deleted. Please ensure that the component is operating as part of a transaction. + Otherwise, you may encounter an Exception such as: + java.lang.IllegalArgumentException: Removing a detached instance ....Optional. - + - The JPA entity manager to be used. + A boolean flag that indicates whether the records can be deleted in bulk or are deleted + one record at a time. By default the value is false, that is, the records are bulk deleted.Optional. + + + + + The fully qualified name of the entity class that would be queried from the database. The adapter will automatically + build a JPA Query to be executed based on the entity class name provided.Optional. + + + + + An instance of javax.persistence.EntityManager that will be used to perform the JPA operations. Optional. + + + + + An instance of javax.persistence.EntityManagerFactory that will be used to obtain + an instance of javax.persistence.EntityManager that will perform the JPA operations. Optional. + + + + + A boolean flag indicating whether the select operation is expected to return a single result or a List of results. + If this flag is set to true, the single entity selected is sent as the payload + of the message. If multiple entities are returned, an exception is thrown. + If false, the List of entities is being sent as the payload of the message. + By default the value is false.Optional. + + + + + An implementation of org.springframework.integration.jpa.core.JpaOperations that would be used to perform the JPA operations. + It is recommended not to provide an implementation of your own but use the default + org.springframework.integration.jpa.core.DefaultJpaOperations implementation. Either of the + entity-manager, entity-manager-factory or + jpa-operations attributes is to be used. Optional. + + + + + The JPA QL that needs to be executed by this adapter.Optional. + + + + + The named query that needs to be executed by this adapter.Optional. + + + + + The native query that will be executed by this adapter. Either of the jpa-query, + named-query,entity-class or native-query + attributes are to be used. Optional. + + + + + An implementation of o.s.i.jpa.support.parametersource.ParameterSource + which will be used to resolve the values of the parameters provided in the query. Ignored if entity-class + attribute is provided.Optional. + + + + + Maximum amount of time in milliseconds to wait when sending a message to the channel.Optional. - - As we can see above these 4 attributes of the outbound-channel-adapter - are all we need to configure it to accept entities over the input channel and process - them to PERSIST,MERGE or DELETE - it from the underlying data source. +
+
+
+ Outbound Channel Adapter + + The JPA Outbound channel adapter allows you to accept messages over a + request channel. The payload can either be used as the entity to be persisted, + or used along with the headers in parameter expressions for a defined JPQL query to be executed. + + In the following sub sections we shall see what those possible ways of performing + these operations are. +
+ Using an Entity Class + + The XML snippet below shows how we can use the Outbound Channel + Adapter to persist an entity to the database. + + ]]> + + + + The channel over which a valid JPA entity will be + sent to the JPA Outbound Channel Adapter. + + + + + The fully qualified name of the entity class that + would be accepted by the adapter to be persisted + in the database. You can actually leave off this + attribute in most cases as the adapter can determine + the entity class automatically from the Spring Integration + Message payload. + + + + + The operation that needs to be done by the adapter, valid values are + PERSIST, MERGE + and DELETE. The default value + is MERGE. + + + + + The JPA entity manager to be used. + + + + + As we can see above these 4 attributes of the outbound-channel-adapter + are all we need to configure it to accept entities over the input channel and process + them to PERSIST,MERGE or DELETE + it from the underlying data source. +
Using JPA Query Language (JPA QL) - - We have seen in the above sub section how to perform a PERSIST action using an entity - We will now see how to use the outbound channel adapter which uses JPA QL (Java Persistence API Query Language) - - + We have seen in the above sub section how to perform a PERSIST action using an entity + We will now see how to use the outbound channel adapter which uses JPA QL (Java Persistence API Query Language) + + ]]> ]]> ]]> - + The input channel over which the message is being sent to the outbound @@ -434,7 +671,7 @@ the parameter names specified in the JPA QL specified in the query attribute - + The parameter sub element accepts an attribute name which corresponds to the named parameter specified in the provided JPA QL (point 2 in the above mentioned sample). The value of the parameter can either be static or can be derived @@ -448,11 +685,11 @@ whose value is represented by the value attribute. By default the type is assumed to be a java.lang.String. - + ]]> - + As seen in the above snippet, it is perfectly valid to use multiple parameter sub elements within an outbound channel adapter tag and derive some parameters using expressions and some with static value. However, care should be taken not to specify the same parameter name multiple times, and, provide one parameter sub element for @@ -460,40 +697,39 @@ level and name where level attribute is a static value of type java.lang.Integer, where as the name attribute is derived from the payload of the message - - Though specifying select is valid for JPA QL, it makes no sense as outbound channel adapters will not be - returning any result. If you want to select some values, consider using the outbound gateway instead. - - + + Though specifying select is valid for JPA QL, it makes no sense as outbound channel adapters will not be + returning any result. If you want to select some values, consider using the outbound gateway instead. +
Using Native Queries - - - In this section we will see how to use native queries to perform the operations using - JPA outbound channel adapter. Using native queries is similar to using JPA QL, - except that the query specified here is a native database query. By choosing - native queries we lose the database vendor independence which we get using JPA QL. - - - One of the things we can achieve using native queries is to perform database inserts, which - is not possible using JPA QL (To perform inserts we send JPA entities to the channel adapter as we have seen earlier). - Below is a small xml fragment that demonstrates the use of native query to insert values in a table. Please note that we - have only mentioned the important attributes below. All other attributes like channel, - entity-manager and the parameter sub element has the same semantics as when we use - JPA QL. - - - Please be aware that named parameters may not be supported - by your JPA provider in conjunction with native SQL queries. - While they work fine using Hibernate, OpenJPA and EclipseLink - do NOT support them: https://issues.apache.org/jira/browse/OPENJPA-111 + + + In this section we will see how to use native queries to perform the operations using + JPA outbound channel adapter. Using native queries is similar to using JPA QL, + except that the query specified here is a native database query. By choosing + native queries we lose the database vendor independence which we get using JPA QL. + + + One of the things we can achieve using native queries is to perform database inserts, which + is not possible using JPA QL (To perform inserts we send JPA entities to the channel adapter as we have seen earlier). + Below is a small xml fragment that demonstrates the use of native query to insert values in a table. Please note that we + have only mentioned the important attributes below. All other attributes like channel, + entity-manager and the parameter sub element has the same semantics as when we use + JPA QL. + + + Please be aware that named parameters may not be supported + by your JPA provider in conjunction with native SQL queries. + While they work fine using Hibernate, OpenJPA and EclipseLink + do NOT support them: https://issues.apache.org/jira/browse/OPENJPA-111 - Section 3.8.12 of the JPA 2.0 spec states: "Only positional - parameter binding and positional access to result items may - be portably used for native queries." - - + @@ -526,9 +762,11 @@
- - We have now seen four possible ways of defining the outbound-channel-adapter in the previous sub sections. - We will now see how to use outbound gateways in the next section. -
Configuration Parameter Reference ]]> ]]> ]]> - - - - Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Optional. - - - - - The channel from which the outbound adapter will receive messages for performing the desired operation. - - - - - The fully qualified name of the entity class for the JPA Operation. - The attributes entity-class, query and named-query are mutually exclusive. Optional - - - - - An instance of javax.persistence.EntityManager that will be used to perform the JPA operations. Optional. - - - - - An instance of javax.persistence.EntityManagerFactory that will be used to - obtain an instance of javax.persistence.EntityManager that will perform the JPA operations. Optional. - - - - - An implementation of org.springframework.integration.jpa.core.JpaOperations that would be used to perform the JPA operations. - It is recommended not to provide an implementation of your own but use the default - org.springframework.integration.jpa.core.DefaultJpaOperations implementation. Either of the - entity-manager, entity-manager-factory or - jpa-operations attributes is to be used. Optional. - - - - - The JPA QL that needs to be executed by this adapter.Optional. - - - - - The named query that needs to be executed by this adapter.Optional. - - - - - The native query that will be executed by this adapter. Either of the jpa-query, - named-query or native-query attributes are to be used. Optional. - - - - - The order for this consumer when multiple consumers are registered thereby - managing load- balancing and/or failover. Optional (Defaults to Ordered.LOWEST_PRECEDENCE). - - - - - An instance of org.springframework.integration.jpa.support.parametersource.ParameterSourceFactory - that will be used to get an instance of org.springframework.integration.jpa.support.parametersource.ParameterSource - which will be used to resolve the values of the parameters provided in the query. - Ignored if operations are performed using a JPA entity. If a parameter sub element is used, the factory must be of - type org.springframework.integration.jpa.support.parametersource.ExpressionEvaluatingParameterSourceFactory. Optional. - - - - - Accepts one of the PERSIST,MERGE or DELETE. Indicates the operation that the adapter needs to perform. - Relevant only if an entity is being used for JPA operations. - Ignored if JPA QL, named query or native query is provided. Defaults to MERGE. Optional. - - - - - 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.Optional. - - - - - Defines the transaction management attributes and the reference to transaction manager to be used by the JPA - adapter.Optional. - - - - - One or more parameter attributes, one for each parameter used in the query. The value or expression - provided will be evaluated to compute the value of the parameter.Optional. - - - - + + + + Lifecycle attribute signaling if this component should be started during Application Context startup. Defaults to true. Optional. + + + + + The channel from which the outbound adapter will receive messages for performing the desired operation. + + + + + The fully qualified name of the entity class for the JPA + Operation. The attributes entity-class, + query and named-query + are mutually exclusive. Optional. + + + + + An instance of javax.persistence.EntityManager that will be used to perform the JPA operations. Optional. + + + + + An instance of javax.persistence.EntityManagerFactory that will be used to + obtain an instance of javax.persistence.EntityManager that will perform the JPA operations. Optional. + + + + + An implementation of org.springframework.integration.jpa.core.JpaOperations that would be used to perform the JPA operations. + It is recommended not to provide an implementation of your own but use the default + org.springframework.integration.jpa.core.DefaultJpaOperations implementation. Either of the + entity-manager, entity-manager-factory or + jpa-operations attributes is to be used. Optional. + + + + + The JPA QL that needs to be executed by this adapter.Optional. + + + + + The named query that needs to be executed by this adapter.Optional. + + + + + The native query that will be executed by this adapter. Either of the jpa-query, + named-query or native-query attributes are to be used. Optional. + + + + + The order for this consumer when multiple consumers are registered thereby + managing load- balancing and/or failover. Optional (Defaults to Ordered.LOWEST_PRECEDENCE). + + + + + An instance of o.s.i.jpa.support.parametersource.ParameterSourceFactory + that will be used to get an instance of o.s.i.jpa.support.parametersource.ParameterSource + which will be used to resolve the values of the parameters provided in the query. + Ignored if operations are performed using a JPA entity. If a parameter sub element is used, the factory must be of + type ExpressionEvaluatingParameterSourceFactory + located in package o.s.i.jpa.support.parametersource. Optional. + + + + + Accepts one of the PERSIST,MERGE or DELETE. Indicates the operation that the adapter needs to perform. + Relevant only if an entity is being used for JPA operations. + Ignored if JPA QL, named query or native query is provided. Defaults to MERGE. Optional. + + + + + 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.Optional. + + + + + Defines the transaction management attributes and the reference to transaction manager to be used by the JPA + adapter.Optional. + + + + + One or more parameter attributes, one for each parameter used in the query. The value or expression + provided will be evaluated to compute the value of the parameter.Optional. + + +
-
- Outbound Gateway - - - Outbound gateways are similar to outbound channel adapters except that it can also be used to - get a result on the reply channel after performing - the given JPA operation. - We recommend you to first review the outbound channel adapter section above, as most of the common concepts have been - explained there. - - - Simlar to the outbound-channel-adapter, we can use - - - Entity classes - - - - JPA Query Language (JPQL) - - - - Native query - - - Named query - - - for performing various JPA operations. We will be seeing each of these in the following four sub sections. Since we are assuming - you are already familiar with the outbound-channel-adapter, we will only discuss portions relevant to - outbound-gateway. - - -
- Differences Between the <emphasis>UPDATING</emphasis> and <emphasis>RETRIEVING</emphasis> Gateways - - JPA outbound gateways are either UPDATING or RETRIEVING - types. The type is specified using the gateway-type attribute. - If this attribute is not specified, the gateway type defaults to an UPDATING - gateway - - - Whenever the gateway is used to perform an action that updates or deletes some records in the - database, you need to use an UPDATING gateway. If an entity is - used, a merged/persisted entity is returned. In any other case - the number of records affected (updated or deleted) are returned. - - - When retrieving data from the database, we use a RETRIEVING - gateway. With a RETRIEVING gateway, we can use either - JPA QL, Named Query or Native Query for selecting the data and retrieving the result. - -
-
- Using Entity class - - We will see below an xml snippet that declares an outbound-gateway using - entity class. - - ]]> - - - This is the request channel for the outbound gateway, this is similar - to the channel attribute of the outbound-channel-adapter - - - - - This is where a gateway differs from an outbound adapter, this is the channel over - which the reply of the JPA operation performed is received. If,however, you are not interested in the - reply received and just want to perform the operation, then outbound-channel-adapter - is an appropriate choice. In above case, where we are using entity class, the reply will - be the entity object that was created/merged as a result of the JPA operation performed. - - - - Valid values are RETRIEVING and UPDATING. - This attribute is optional and in it's absence the value - defaults to UPDATING. - - - -
- -
- Using JPA Query Language (JPA QL) - - We will now see how we can use JPA QL in an outbound gateway. Below xml snippet is a declaration of the - outbound-gateway. - - - - -]]> - - - - The JPA QL that will be executed by the gateway. Since the - gateway-type is UPDATING, only update and - delete JPA QL will be acceptable. - - - - - When sending a message with a String payload and containing a header rollNumber - with a long value, the last name of the student with the provided roll number - is updated to the value provided in the message payload. When using an - UPDATING gateway, the return value is always an integer - value which denotes the number of records affected by execution of the JPA QL. - - - The following is a sample RETRIEVING type of an outbound gateway below. - - - - - ]]> - - The above sample is pretty straightforward and simple. The gateway type if - RETRIEVING and the jpa-query is a select query. - -
-
- Using Native query - - Using a native query is similar to using the JPA QL except that the jpa-query attribute is - replaced by the native-query attribute, which holds the native query to execute. - -
-
- Using Named query - - Using a named query is also very similar to using a JPA QL except that - the named-query attribute is used instead, as seen in the xml snippet below - - - - -]]> +
+ Outbound Gateways + + The JPA Inbound Channel Adapter allows you to poll a database in + order to retrieve one or more JPA entities and the retrieved data + is consequently used to start a Spring Integration flow using the + retrieved data as message payload. + + + Additionally, you may use JPA Outbound Channel Adapters at + the end of your flow in order to persist data, essentially terminating + the flow at the end of the persistence operation. + + + However, how can you execute JPA persistence operation in the middle + of a flow? For example, you may have business data that you are + processing in your Spring Integration message flow, that you would + like to persist, yet you still need to execute other components + further downstream. Or instead of polling the database using a + poller, you rather have the need to execute JPQL queries and retrieve + data actively which then is used to being processed in subsequent + components within your flow. + + + This is where JPA Outbound Gateways come into play. They give you + the ability to persist data as well as retrieving data. To facilitate + these uses, Spring Integration provides two types of JPA Outbound + Gateways: + + + Updating Outbound Gateway + Retrieving Outbound Gateway + + + Whenever the Outbound Gateway is used to perform an action that + saves, updates or soley deletes some records in the database, you + need to use an Updating Outbound Gateway gateway. + If for example an entity is used to persist it, + then a merged/persisted entity is returned as a result. In + other cases the number of records affected (updated or deleted) + is returned instead. + + + When retrieving (selecting) data from the database, we + use a Retrieving Outbound Gateway. With a + Retrieving Outbound Gateway gateway, we can + use either JPQL, Named Queries (native or JPQL-based) or Native + Queries (SQL) for selecting the data and retrieving the results. + + + An Updating Outbound Gateway is + functionally very similar to an Outbound Channel Adapter, + except that an Updating Outbound Gateway + is used to send a result to the Gateway's reply channel + after performing the given JPA operation. + + + A Retrieving Outbound Gateway + is quite similar to an Inbound Channel Adapter. + + + We recommend you to first refer to the JPA Outbound Channel Adapter + section and the JPA Inbound Channel Adapter sections above, as + most of the common concepts are being explained there. + + + This similarity was the main factor to use the central + JpaExecutor class to unify common functionality + as much as possible. + + + Common for all JPA Outbound Gateways and simlar to the + outbound-channel-adapter, we can use + + + + Entity classes + + + JPA Query Language (JPQL) + + + Native query + + + Named query + + + + for performing various JPA operations. For configuration examples + please see . + +
+ Common Configuration Parameters + + JPA Outbound Gateways always have access to the Spring Integration + Message as input. As such the following parameters are available: + + parameter-source-factory + + An instance of + o.s.i.jpa.support.parametersource.ParameterSourceFactory + that will be used to get an instance of + o.s.i.jpa.support.parametersource.ParameterSource. + The ParameterSource is used to resolve the + values of the parameters provided in the query. The + parameter-source-factory attribute is ignored, + if operations are performed using a JPA entity. If a + parameter sub-element is used, the factory + must be of type ExpressionEvaluatingParameterSourceFactory, + located in package o.s.i.jpa.support.parametersource. + Optional. + + use-payload-as-parameter-source + + If set to true, the payload of the Message + will be used as a source for providing parameters. If set to + false, the entire Message will be available + as a source for parameters. If no JPA Parameters are passed in, + this property will default to true. + This means that using a default + BeanPropertyParameterSourceFactory, the + bean properties of the payload will be used as a source for + parameter values for the to-be-executed JPA query. However, if + JPA Parameters are passed in, then this property will by default + evaluate to false. The reason is that JPA + Parameters allow for SpEL Expressions to be provided and therefore + it is highly beneficial to have access to the entire Message, + including the Headers. +
+
+ Updating Outbound Gateway + -
- Configuration Parameter Reference - The following shows various attributes that can be used for the JPA outbound gateway - Only the attributes which are different than those explained earlier are mentioned here. + + + + + + + ]]> + + + + + The channel from which the outbound gateway will receive messages for performing + the desired operation. This attribute is similar to channel attribute of the outbound-channel-adapter.Optional. + + + + + The channel to which the gateway will send the response after performing the required JPA operation. + If this attribute is not defined, the request message must have a replyChannel header. Optional. + + + + + Specifies the time the gateway will wait to send the result to the reply channel. + Only applies when the reply channel itself might block the send (for example a bounded QueueChannel that is currently full). + By default the Gateway will wait indefinitely. The value is specified in milliseconds. Optional. + + + +
+
+ Retrieving Outbound Gateway + + + + + + + + ]]> + + + + A boolean flag indicating whether the select operation is expected to return a single result or a List of results. + If this flag is set to true, the single entity selected is sent as the payload + of the message. If multiple entities are returned, an exception is thrown. + If false, the List of entities is being sent as the payload of the message. + By default the value is false.Optional. + + + + + This non zero, non negative integer value tells the adapter not to select more than given number + of rows on execution of the select operation. By default, if this attribute is not set, + all the possible records are selected by given query.Optional. + + + + + + When choosing to delete entities upon retrieval and you have + retrieved a collection of entities, please be aware that by + default entities are deleted on a per entity basis. This may + cause performance issues. - - - - -]]> - - - - A boolean flag indicating whether the select operation is expected to return a single result or a List of results. - If this flag is set to true, the single entity selected is sent as the payload - of the message. If multiple entities are returned, an exception is thrown. - If false, the List of entities is being sent as the payload of the message. - By default the value is false.Optional. - - - - - Valid values are UPDATING and RETRIEVING, - the value defaults to UPDATING. - The difference between these types of gateways is explained earlier in the manual.Optional. - - - - - This non zero, non negative integer value tells the adapter not to select more than given number - of rows on execution of the select operation. By default, if this attribute is not set, - all the possible records are selected by given query.Optional. - - - - - The channel to which the gateway will send the response after performing the required JPA operation. - If this attribute is not defined, the request message must have a replyChannel header. Optional. - - - - - Specifies the time the gateway will wait to send the result to the reply channel. - Only applies when the reply channel itself might block the send (for example a bounded QueueChannel that is currently full). - By default the Gateway will wait indefinitely. The value is specified in milliseconds. Optional. - - - - - The channel from which the outbound gateway will receive messages for performing - the desired operation. This attribute is similar to channel attribute of the outbound-channel-adapter.Optional. - - - + + Alternatively, you can set attribute deleteInBatch + to true, which will perform a batch delete. + However, please be aware of the limitation that in that case + cascading deletes are not supported. + + + JSR 317: Java™ Persistence 2.0 states + in chapter Chapter 4.10, Bulk Update and Delete Operations + that: + + + "A delete operation only applies to entities of the specified + class and its subclasses. It does not cascade to related + entities." + + + For more information please see + JSR 317: Java™ Persistence 2.0 + + +
+
+ JPA Outbound Gateway Samples + + This section contains various examples of the Updating Outbound Gateway + and Retrieving Outbound Gateway + + Update using an Entity Class + + In this example an Updating Outbound Gateway + is persisted using solely the entity class + org.springframework.integration.jpa.test.entity.Student + as JPA defining parameter. + + ]]> + + + + This is the request channel for the outbound gateway, + this is similar to the channel + attribute of the outbound-channel-adapter + + + + + This is where a gateway differs from an outbound adapter, + this is the channel over which the reply of the performed + JPA operation is received. If,however, you are not + interested in the reply received and just want to perform + the operation, then using a JPA outbound-channel-adapter + is the appropriate choice. In above case, where we are + using entity class, the reply will be the entity object + that was created/merged as a result of the JPA operation. + + + + Update using JPQL + + In this example, we will see how we can update an entity using + the Java Persistence Query Language (JPQL). For this we use an + Updating Outbound Gateway. + + + + + ]]> + + + + The JPQL query that will be executed by the gateway. Since + an Updating Outbound Gateway is used, + only update and delete + JPQL queries would be sensible choices. + + + + + When sending a message with a String payload and containing a header rollNumber + with a long value, the last name of the student with the provided roll number + is updated to the value provided in the message payload. When using an + UPDATING gateway, the return value is always an integer + value which denotes the number of records affected by execution of the JPA QL. + + Retrieving an Entity using JPQL + + The following examples uses a Retrieving Outbound Gateway + together with JPQL to retrieve (select) one or more entities from + the database. + + + + + + ]]> + + Update using a Named Query + + Using a Named Query is basically the same as using a JPQL query + directly. The difference is that the named-query + attribute is used instead, as seen in the xml snippet below. + + + + + ]]> + + + You can find a complete Sample application for using Spring + Integration's JPA adapter at: + + https://github.com/SpringSource/spring-integration-samples/tree/master/basic/jpa +
-
- Inbound Channel Adapter - - An inbound channel adapter is used to execute a select query over the - database using JPA QL and return the result. The message payload will be either a single - entity or a List of entities. Below is a sample xml snippet that shows - a sample usage of inbound-channel-adapter. - - ]]> - - -]]> - - - - - The channel over which the inbound-channel-adapter will put the - messages with the payload received after executing the provided JPA QL in the - query attribute. - - - - - The EntityManager instance that will be used to perform the - required JPA operations. - - - - - Attribute signalling if the component should be automatically started on startup of - the Application Context. The value defaults to true - - - - - The JPA QL that needs to be executed and whose result needs to be sent out as the - payload of the message - - - - - The attribute that tells if the executed JPA QL gives a single entity in the result - or a List of entities. If the value is set to true, - the single entity retrieved is sent as the payload of the message. If, however, multiple - results are returned after setting this to true, a - MessageHandlingException is thrown. The value defaults to false - - - - - Set this value to true if you want - to delete the rows received after execution of the query. - Please ensure that the component is operating as part - of a transaction. - - Otherwise, you may encounter an Exception such as: - java.lang.IllegalArgumentException: Removing - a detached instance ... - - - -
- Configuration Parameter Reference - - - ]]> -
- - - - This Lifecycle attribute signaled if this component should be started during startup of the Application Context. - This attribute defaults to true.Optional. - - - - - The channel to which the adapter will send a message with the payload that was received after - performing the desired JPA operation. - - - - - A boolean flag that indicates whether the records selected are to be deleted - after they are being polled by the adapter. By default the value is false, - that is, the records will not be deleted. Please ensure that the component is operating as part of a transaction. - Otherwise, you may encounter an Exception such as: - java.lang.IllegalArgumentException: Removing a detached instance ....Optional. - - - - - A boolean flag that indicates whether the records can be deleted in bulk or are deleted - one record at a time. By default the value is false, that is, the records are bulk deleted.Optional. - - - - - The fully qualified name of the entity class that would be queried from the database. The adapter will automatically - build a JPA Query to be executed based on the entity class name provided.Optional. - - - - - An instance of javax.persistence.EntityManager that will be used to perform the JPA operations. Optional. - - - - - An instance of javax.persistence.EntityManagerFactory that will be used to obtain - an instance of javax.persistence.EntityManager that will perform the JPA operations. Optional. - - - - - A boolean flag indicating whether the select operation is expected to return a single result or a List of results. - If this flag is set to true, the single entity selected is sent as the payload - of the message. If multiple entities are returned, an exception is thrown. - If false, the List of entities is being sent as the payload of the message. - By default the value is false.Optional. - - - - - An implementation of org.springframework.integration.jpa.core.JpaOperations that would be used to perform the JPA operations. - It is recommended not to provide an implementation of your own but use the default - org.springframework.integration.jpa.core.DefaultJpaOperations implementation. Either of the - entity-manager, entity-manager-factory or - jpa-operations attributes is to be used. Optional. - - - - - The JPA QL that needs to be executed by this adapter.Optional. - - - - - The named query that needs to be executed by this adapter.Optional. - - - - - The native query that will be executed by this adapter. Either of the jpa-query, - named-query,entity-class or native-query - attributes are to be used. Optional. - - - - - An implementation of org.springframework.integration.jpa.support.parametersource.ParameterSource - which will be used to resolve the values of the parameters provided in the query. Ignored if entity-class - attribute is provided.Optional. - - - - - Maximum amount of time in milliseconds to wait when sending a message to the channel.Optional. - - - -
- - You can find more samples for using spring integration's JPA adapter at: - https://github.com/SpringSource/spring-integration-samples/tree/master/basic/jpa - \ No newline at end of file diff --git a/src/reference/docbook/whats-new.xml b/src/reference/docbook/whats-new.xml index 9b2919fdba..18525c8e4d 100644 --- a/src/reference/docbook/whats-new.xml +++ b/src/reference/docbook/whats-new.xml @@ -61,12 +61,31 @@
New Components -
- JPA Endpoints - - Endpoints are now available for manipulating JPA entity objects. - -
+
+ JPA Endpoints + + Spring Integration now includes components for the Java Persistence + API (JPA) for retrieving and persisting JPA entity objects. The + JPA Adapter includes the following components: + + + + Inbound Channel Adapter + + + Outbound Channel Adapter + + + Updating Outbound Gateway + + + Retrieving Outbound Gateway + + + + For more information please see + +
Framework Refactoring