This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Integration 6.4.0!

Namespace Support

When using XML namespace support, the underlying parser classes instantiate the relevant Java classes for you. Thus, you typically need not deal with the inner workings of the JPA adapter. This section documents the XML namespace support provided by Spring Integration and shows you how to use the XML Namespace support to configure the JPA components.

Common XML Namespace Configuration Attributes

Certain configuration parameters are shared by all JPA components:

auto-startup

Lifecycle attribute that signals whether 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 the adapter uses to create the EntityManager. You must provide this attribute, the entity-manager attribute, or the jpa-operations attribute.

entity-manager

The reference to the JPA Entity Manager that the component uses. You must provide this attribute, the entity-manager-factory attribute, or the jpa-operations attribute.

Usually, your Spring application context defines only a JPA entity manager factory, and the EntityManager is injected by using the @PersistenceContext annotation. This approach does not apply for the Spring Integration JPA components. Usually, injecting the JPA entity manager factory is best, but, when you want to inject an EntityManager explicitly, you have to define a SharedEntityManagerBean. For more information, see the relevant Javadoc.

The following example shows how to explicitly include an entity manager factory:

<bean id="entityManager"
      class="org.springframework.orm.jpa.support.SharedEntityManagerBean">
    <property name="entityManagerFactory" ref="entityManagerFactoryBean" />
</bean>

jpa-operations

A reference to a bean that implements 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). If you use the jpa-operations attribute, you must not provide the JPA entity manager or JPA entity manager factory, because JpaOperations wraps the necessary datasource.

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 or 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 indicates the type of object to persist. If not specified (for persist operations) the entity class is automatically retrieved from the message’s payload.

jpa-query

Defines the JPA query (Java Persistence Query Language) to be used.

native-query

Defines the native SQL query to be used.

named-query

Refers to a named query. A named query can be defined in either Native SQL or JPAQL, but the underlying JPA persistence provider handles that distinction internally.

Providing JPA Query Parameters

To provide parameters, you can use the parameter XML element. It has a mechanism that lets you provide parameters for queries that are based on either the Java Persistence Query Language (JPQL) or native SQL queries. You can also provide parameters for named queries.

Expression-based Parameters

The following example shows how to set an expression-based parameter:

<int-jpa:parameter expression="payload.name" name="firstName"/>

Value-based Parameters

The following example shows how to set a value-based parameter:

<int-jpa:parameter name="name" type="java.lang.String" value="myName"/>

Positional Parameters

The following example shows how to set an expression-based parameter:

<int-jpa:parameter expression="payload.name"/>
<int-jpa:parameter type="java.lang.Integer" value="21"/>

Transaction Handling

All JPA operations (such as INSERT, UPDATE, and DELETE) require a transaction to be active whenever they are performed. For inbound channel adapters, you need do nothing special. It works similarly to the way we configure transaction managers with pollers that are used with other inbound channel adapters. The following XML example configures a transaction manager that uses a poller with an inbound channel adapter:

<int-jpa:inbound-channel-adapter
    channel="inboundChannelAdapterOne"
    entity-manager="em"
    auto-startup="true"
    jpa-query="select s from Student s"
    expect-single-result="true"
    delete-after-poll="true">
    <int:poller fixed-rate="2000" >
        <int:transactional propagation="REQUIRED"
            transaction-manager="transactionManager"/>
    </int:poller>
</int-jpa:inbound-channel-adapter>

However, you may need to specifically start a transaction when using an outbound channel adapter or gateway. If a DirectChannel is an input channel for the outbound adapter or gateway and if the transaction is active in the current thread of execution, the JPA operation is performed in the same transaction context. You can also configure this JPA operation to run as a new transaction, as the following example shows:

<int-jpa:outbound-gateway
    request-channel="namedQueryRequestChannel"
    reply-channel="namedQueryResponseChannel"
    named-query="updateStudentByRollNumber"
    entity-manager="em"
    gateway-type="UPDATING">
    <int-jpa:parameter name="lastName" expression="payload"/>
    <int-jpa:parameter name="rollNumber" expression="headers['rollNumber']"/>
		<int-jpa:transactional propagation="REQUIRES_NEW"
        transaction-manager="transactionManager"/>
</int-jpa:outbound-gateway>

In the preceding example, the transactional element of the outbound gateway or adapter specifies 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 use an ExecutorChannel, you must have the transactional element, because the invoking client’s transaction context is not propagated.

Unlike the transactional element of the poller, which is defined in Spring Integration’s namespace, the transactional element for the outbound gateway or adapter is defined in the JPA namespace.