From b9d73f06fa700688eb2a4fef678398f2174bc51e Mon Sep 17 00:00:00 2001 From: Amol Nayak Date: Sun, 20 May 2012 18:34:42 +0530 Subject: [PATCH] INT-2440: Update the reference documentation for the JPA adapter chapter in the manual. INT-2440 Polishing (JPA Doc) --- src/reference/docbook/index.xml | 4 + src/reference/docbook/jpa.xml | 762 +++++++++++++++++--------------- 2 files changed, 400 insertions(+), 366 deletions(-) diff --git a/src/reference/docbook/index.xml b/src/reference/docbook/index.xml index 01f1c9546b..71831d6ffa 100644 --- a/src/reference/docbook/index.xml +++ b/src/reference/docbook/index.xml @@ -65,6 +65,10 @@ Artem Bilan + + Amol + Nayak + © SpringSource Inc., 2012 diff --git a/src/reference/docbook/jpa.xml b/src/reference/docbook/jpa.xml index c10b5b932d..0cc3e8498a 100644 --- a/src/reference/docbook/jpa.xml +++ b/src/reference/docbook/jpa.xml @@ -27,7 +27,7 @@ operations on the targeted database by sending/receiving messages to them. - The above operations can be performed using either one of the of the + The above operations can be performed using either of the following: @@ -56,7 +56,7 @@
Supported Persistence Providers - The Spring Integration JPA support is being tested using the following + The Spring Integration JPA support has been tested using the following persistence providers: @@ -79,10 +79,10 @@ class which in turn will use an implementation of the org.springframework.integration.jpa.core.JpaOperations interface. JpaOperations operates like a - typical Data Access Object (Dao) and provides methods such as + typical Data Access Object (DAO) and provides methods such as find, - persiste, - executeUpdate etc. For most use-cases the provided + 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 @@ -90,8 +90,8 @@ behavior. - That means, that for initializing a JpaExecutor - you have to use one of 3 available constructors that accept either a: + For initializing a JpaExecutor + you have to use one of 3 available constructors that accept one of: @@ -107,7 +107,7 @@ Example - The following example of an JPA Outbound Gateway is purely configured + The following example of a JPA 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. @@ -149,7 +149,7 @@ ]]> - When using XML Namespace Support the unlerying parser classes will + 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 @@ -160,7 +160,7 @@
Common Configuration Attributes - Certain configuration parameters are shared among all Jpa components and are described below: + Certain configuration parameters are shared amongst all JPA components and are described below: auto-startup @@ -182,7 +182,7 @@ entity-manager-factory The reference to the JPA Entity Manager Factory - that will be used by the adapter to create the EntityManager. + 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. @@ -197,12 +197,12 @@ 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 in - regards to the Spring Integration Jpa components. + 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, + a SharedEntityManagerBean. For more information, please see the relevant JavaDoc. @@ -218,7 +218,7 @@ of the JpaOperations interface, instead of relying on the default implementation org.springframework.integration.jpa.core.DefaultJpaOperations. - As JpaOperations wraps the necessay + 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. @@ -226,9 +226,9 @@ entity-class - The reference to the JPA Persistence Entity. The exact sermantics of - this attribute vary, depending wether we are performing a persist/update - operation or wether we are retrieving objects from the database. + 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 @@ -289,17 +289,63 @@
Transaction Handling - TBD + 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. + + + ]]> + + ]]> + ]]> + + 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 to persist it to the - database or the Message payload and its headers can be used as parameters - for a defined JPQL query to be executed. + 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. @@ -359,7 +405,7 @@ We will now see how to use the outbound channel adapter which uses JPA QL (Java Persistence API Query Language) ]]> ]]> @@ -374,7 +420,7 @@ The JPA QL that needs to be executed.This query may contain parameters that will be evaluated - using the jpa:param child tag. + using the parameter child tag. @@ -390,9 +436,8 @@ - We will see a bit more about the param sub element here. The param 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 + 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 using an expression. The static value and the expression to derive the value is specified using the value and the expression attributes respectively. These attributes are mutually exclusive. @@ -401,19 +446,19 @@ If the value attribute is specified we can provide an optional type attribute. The value of this attribute is the fully qualified name of the class whose value is represented by the value attribute. By default - the type is assumed to be a java.lang.String. + the type is assumed to be a java.lang.String. - - + + ]]> - As seen in the above snippet, it is perfectly valid to use multiple param sub elements within an outbound channel adapter + 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 param sub element for + be taken not to specify the same parameter name multiple times, and, provide one parameter sub element for each named parameter specified in the JPA query. For example, we are specifying two parameters 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 + 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 @@ -422,7 +467,7 @@
- Using Native query + Using Native Queries In this section we will see how to use native queries to perform the operations using @@ -435,7 +480,7 @@ 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 param sub element have the same semantics as when we use + entity-manager and the parameter sub element has the same semantics as when we use JPA QL. @@ -449,8 +494,7 @@ be portably used for native queries." @@ -461,25 +505,11 @@ The native query that will be executed by this outbound channel adapter - - - The flag that indicates whether the specified query is a JPA QL or a native query. Not specifying this attribute - or setting it's value to false will lead to the value specified in the query attribute - to be evaluated as a JPA QL. - - - - - TODO: The above xml declaration will change and the native-query may no longer hold the flag but will become - the native query itself. However, the document is as per the code currently. Change this when the changes are made in the code - - -
- Using Named query + Using Named Queries We will now see how to use named queries after seeing using entity, JPA QL and native query in previous sub sections. @@ -488,7 +518,7 @@ see how named JPA named queries are defined. - In our case, if we have an entity called Student, then we have the following in the class to define + In our case, if we have an entity called Student, then we have the following in the class to define two named queries selectStudent and updateStudent. Below is a way to define named queries using annotations @@ -538,34 +568,129 @@ public class Student {
Configuration Parameter Reference + jpa-operations="" ]]> - - + ]]> + ]]> ]]> + + + + 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. + + + +
Outbound Gateway - Outbound gateways are similar to outbound channel adapter except that it can also be used to + 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 . If you are directly referring to this outbound gateway section, - we would recommend you to first go through the outbound channel adapter section given above, as most of the common concepts have been + 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. @@ -592,25 +717,23 @@ public class Student {
- Difference between <emphasis>UPDATING</emphasis> and <emphasis>RETRIEVING</emphasis> gateway + Differences Between the <emphasis>UPDATING</emphasis> and <emphasis>RETRIEVING</emphasis> Gateways - Before we continue, let us see what are the types of JPA outbound 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 if defaulted to an UPDATING - type of the gateway + If this attribute is not specified, the gateway type defaults to an UPDATING + gateway - Whenever the gateway intends to perform an action that updates or deletes some records in the - database using JPA, you need to use an UPDATING type of gateway. If an entity is + 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. - If the calling application requires to select/retrieve some data from the database - using outbound-gateway, we use a RETRIEVING type - of gateway. With a RETRIEVING type of gateway, we can use either - of JPA QL, Named Query or Native Query for selecting the data and retrieving the result. + 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.
@@ -656,7 +779,7 @@ public class Student { @@ -672,31 +795,40 @@ public class Student { - On sending a message with string payload and containing a header rollNumber + 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 a gateway of type - UPDATING, the return value is always an integer + 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. - - TODO: Show one RETRIEVING type of gateway sample, also somewhere in the manual - show a sample usage of BeanPropertyParameterSource - + + 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 native query is very identical to using the JPA QL except that the query attribute now - holds the native SQL Query and an additional attribute native-query set to - true - (TODO: Change this description once the change for the attribute names is done) + 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 named query is also very similar to using a JPA QL except that we have - the named-query attribute as seen in the xml snippet below + 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 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. + ]]> + + + + 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. + + +
@@ -740,7 +920,7 @@ public class Student { 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 + entity or a List of entities. Below is a sample xml snippet that shows a sample usage of inbound-channel-adapter. ]]> @@ -765,14 +944,14 @@ public class Student { - The EntityManager instance that will be used to perform the + 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 Application Context. The value defaults to true @@ -784,22 +963,15 @@ public class Student { 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, + 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 - - - - - The maximum number of rows that should be retrieved on execution of the given JPA QL. - Relevant only if the query can potentially receive multiple records - + 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 + 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. @@ -813,262 +985,120 @@ public class Student {
Configuration Parameter Reference + jpa-operations="" ]]> - - -]]> -
-
-
- JPA Adapters XML attributes quick reference -
- Common XML Attributes - - Common Attributes - - - - - - - Name - Description - Mandatory - - - - - entity-manager - An instance of javax.persistence.EntityManager - that will be used to perform the JPA operations. - - No - - - entity-manager-factory - An instance of javax.persistence.EntityManagerFactory - that will be used to obtain an instance of javax.persistence.EntityManager - that will perform the JPA operations. Either of entity-manager-factory and - entity-manager attributes is mandatory. - - No - - - jpa-operations - - 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. - - - No - - - query - The JPA QL that needs to be executed by this adapter - No - - - native-query - - The boolean flag that indicates that the string value given in query attribute - is a native query. By default the value is false - (TODO: change this after the changes are made in adapter) - - No - - - named-query - The Named JPA QL that needs to be executed by this adapter - No - - - -
-
-
- Outbound adapter/gateway XML Attributes - - Outbound adapter/gateway Attributes - - - - - - - Name - Description - Mandatory - - - - - channel - - The channel over which the outbound adapter will receive messages for performing the desired operation. - This attribute is relevant for outbound-channel-adapter only. - - Yes - - - request-channel - - The channel over which the outbound gateway will receive messages for performing the desired operation. - This attribute is relevant for outbound-gateway only. This attribute is similar to - channel attribute of the outbound-channel-adapter - - Yes - - - entity-class - - The fully qualified name of the entity class of the entities that would be sent to this adapter to perform JPA Operation - using entity. The attributes entity-class, query and named-query - are mutually exclusive. - - No - - - reply-channel - - The channel over which the gateway will send the response after - performing the required JPA operation. This attribute is relevant for outbound-gateway - only. If this attribute is not defined, the request message must have a - replyChannel header - - No - - - persist-mode - - 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 - - No - - - gateway-type - - Valid values are UPDATING and RETRIEVING, - the value defaults to UPDATING. The difference between these types - of gateways is explained earlier in the manual. This attribute is relevant to - outbound-gateway only - - No - - - parameter-source-factory - - 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 done using JPA entity. - If a param sub element is used, the factory must be of type - org.springframework.integration.jpa.support.parametersource.ExpressionEvaluatingParameterSourceFactory - - No - - - -
-
-
- Inbound adapter XML Attributes - - - - - - - - Name - Description - Mandatory - - - - - channel - - The channel over which the adapter will send a message with the payload - that was received after performing desired the JPA operation - - Yes - - - delete-after-poll - - 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 ... - - No - - - delete-per-row - - 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 - - No - - - max-rows - - 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. - - No - - - expect-single-result - - A boolean flag indicates whether the select operation gives a single - result or a List or results. If this flag is set to true, - the single entity selected is sent as the payload of the message. - If however, multiple entities are selected, an exception is thrown. - If false, the List of entities is being - sent as the payload of the message. Even a single entity will be sent a - List or size one when the value is set to false. - By default the value is false - - No - - - -
+ ]]>
+ + + + 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