出站通道适配器

JPA 出站通道适配器允许您通过请求通道接收消息。有效负载可以作为要持久化的实体使用，也可以与标头一起在参数表达式中用于 JPQL 查询。以下部分介绍了执行这些操作的可能方法。

使用实体类

以下 XML 配置出站通道适配器以将实体持久化到数据库

<int-jpa:outbound-channel-adapter channel="entityTypeChannel"               (1)
    entity-class="org.springframework.integration.jpa.test.entity.Student"  (2)
    persist-mode="PERSIST"                                                  (3)
    entity-manager="em"/ >                                                  (4)

1	通过该通道将有效的 JPA 实体发送到 JPA 出站通道适配器。
2	适配器接受的实体类的完全限定名称，该实体类将在数据库中持久化。实际上，在大多数情况下，您可以省略此属性，因为适配器可以从 Spring Integration 消息有效负载自动确定实体类。
3	适配器要执行的操作。有效值为 `PERSIST`、`MERGE` 和 `DELETE`。默认值为 `MERGE`。
4	要使用的 JPA 实体管理器。

outbound-channel-adapter 的这四个属性将其配置为通过输入通道接受实体，并处理它们以PERSIST、MERGE 或DELETE 底层数据源中的实体。

从 Spring Integration 3.0 开始，PERSIST 或 MERGE 的有效负载也可以是 java.lang.Iterable 类型。在这种情况下，Iterable 返回的每个对象都被视为一个实体，并使用底层的 EntityManager 进行持久化或合并。迭代器返回的空值将被忽略。

从 5.5.4 版开始，配置了 JpaExecutor 并将其 PersistMode 设置为 DELETE 的 JpaOutboundGateway 可以接受 Iterable 有效负载，以便对提供的实体执行批量删除持久操作。

使用 JPA 查询语言 (JPA QL)

上一节演示了如何使用实体执行 PERSIST 操作。本节介绍如何将出站通道适配器与 JPA QL 一起使用。

以下 XML 配置出站通道适配器以将实体持久化到数据库

<int-jpa:outbound-channel-adapter channel="jpaQlChannel"                                      (1)
  jpa-query="update Student s set s.firstName = :firstName where s.rollNumber = :rollNumber"  (2)
  entity-manager="em">                                                                        (3)
    <int-jpa:parameter name="firstName"  expression="payload['firstName']"/>                  (4)
    <int-jpa:parameter name="rollNumber" expression="payload['rollNumber']"/>
</int-jpa:outbound-channel-adapter>

1	通过该输入通道将消息发送到出站通道适配器。
2	要执行的 JPA QL。此查询可能包含使用 `parameter` 元素计算的参数。
3	适配器用于执行 JPA 操作的实体管理器。
4	用于定义 JPA QL（上例中的第 2 点）中指定的参数名称值的元素（每个参数一个）。

parameter 元素接受一个属性，其 name 对应于提供的 JPA QL 中指定的命名参数（上例中的第 2 点）。参数的值可以是静态的，也可以通过使用表达式派生。静态值和派生值的表达式分别使用 value 和 expression 属性指定。这些属性是互斥的。

如果指定了 value 属性，则可以提供一个可选的 type 属性。此属性的值是表示 value 属性值的类的完全限定名称。默认情况下，类型假定为 java.lang.String。以下示例演示了如何定义 JPA 参数

<int-jpa:outbound-channel-adapter ...
>
    <int-jpa:parameter name="level" value="2" type="java.lang.Integer"/>
    <int-jpa:parameter name="name" expression="payload['name']"/>
</int-jpa:outbound-channel-adapter>

如上例所示，您可以在出站通道适配器元素中使用多个 parameter 元素，并使用表达式定义一些参数，使用静态值定义其他参数。但是，请注意不要多次指定相同的参数名称。您应该为 JPA 查询中指定的每个命名参数提供一个 parameter 元素。例如，我们指定了两个参数：level 和 name。level 属性是 java.lang.Integer 类型的静态值，而 name 属性是从消息的有效负载派生的。

尽管为 JPA QL 指定 select 是有效的，但这样做毫无意义。出站通道适配器不返回任何结果。如果要选择某些值，请考虑改用出站网关。

使用原生查询

本节介绍如何使用原生查询来执行 JPA 出站通道适配器的操作。使用原生查询类似于使用 JPA QL，只是查询是本机数据库查询。通过使用原生查询，我们失去了使用 JPA QL 获得的数据库供应商独立性。

通过使用原生查询可以实现的一件事是执行数据库插入，这在 JPA QL 中是不可能的。（要执行插入操作，我们将 JPA 实体发送到通道适配器，如前面所述）。下面是一个小的 xml 片段，它演示了如何使用原生查询将值插入表中。

您的 JPA 提供程序可能不支持将命名参数与原生 SQL 查询结合使用。虽然它们在 Hibernate 中运行良好，但 OpenJPA 和 EclipseLink 不支持它们。请参阅 issues.apache.org/jira/browse/OPENJPA-111。JPA 2.0 规范的第 3.8.12 节指出：“仅位置参数绑定和对结果项的位置访问可用于可移植的原生查询。”

以下示例配置了一个带有原生查询的 outbound-channel-adapter

<int-jpa:outbound-channel-adapter channel="nativeQlChannel"
  native-query="insert into STUDENT_TABLE(FIRST_NAME,LAST_UPDATED) values (:lastName,:lastUpdated)"  (1)
  entity-manager="em">
    <int-jpa:parameter name="lastName" expression="payload['updatedLastName']"/>
    <int-jpa:parameter name="lastUpdated" expression="new java.util.Date()"/>
</int-jpa:outbound-channel-adapter>

1	此出站通道适配器执行的原生查询。

请注意，其他属性（例如 channel 和 entity-manager）以及 parameter 元素具有与 JPA QL 相同的语义。

使用命名查询

使用命名查询类似于使用JPA QL或原生查询，只是我们指定了一个命名查询而不是一个查询。首先，我们介绍如何定义 JPA 命名查询。然后，我们介绍如何声明出站通道适配器以使用命名查询。如果我们有一个名为 Student 的实体，则可以使用 Student 类上的注释来定义两个命名查询：selectStudent 和 updateStudent。以下示例演示了如何执行此操作

@Entity
@Table(name="Student")
@NamedQueries({
    @NamedQuery(name="selectStudent",
        query="select s from Student s where s.lastName = 'Last One'"),
    @NamedQuery(name="updateStudent",
        query="update Student s set s.lastName = :lastName,
               lastUpdated = :lastUpdated where s.id in (select max(a.id) from Student a)")
})
public class Student {

...
}

或者，您可以使用 orm.xml 来定义命名查询，如下例所示

<entity-mappings ...>
    ...
    <named-query name="selectStudent">
        <query>select s from Student s where s.lastName = 'Last One'</query>
    </named-query>
</entity-mappings>

现在我们已经演示了如何使用注释或使用 orm.xml 来定义命名查询，我们现在展示一个小的 XML 片段，该片段使用命名查询定义了一个 outbound-channel-adapter，如下例所示

<int-jpa:outbound-channel-adapter channel="namedQueryChannel"
            named-query="updateStudent"	 (1)
            entity-manager="em">
        <int-jpa:parameter name="lastName" expression="payload['updatedLastName']"/>
        <int-jpa:parameter name="lastUpdated" expression="new java.util.Date()"/>
</int-jpa:outbound-channel-adapter>

1	我们希望适配器在通过通道接收消息时执行的命名查询。

配置参数参考

以下列表显示了可以在出站通道适配器上设置的所有属性

<int-jpa:outbound-channel-adapter
  auto-startup="true"  (1)
  channel=""  (2)
  entity-class=""  (3)
  entity-manager=""  (4)
  entity-manager-factory=""  (5)
  id=""
  jpa-operations=""  (6)
  jpa-query=""  (7)
  named-query=""  (8)
  native-query=""  (9)
  order=""  (10)
  parameter-source-factory=""   (11)
  persist-mode="MERGE"   (12)
  flush="true"   (13)
  flush-size="10"   (14)
  clear-on-flush="true"   (15)
  use-payload-as-parameter-source="true"   (16)
	<int:poller/>
	<int-jpa:transactional/>    (17)
	<int-jpa:parameter/>    (18)
</int-jpa:outbound-channel-adapter>

1	生命周期属性，指示此组件是否应在应用程序上下文启动期间启动。默认为 `true`。可选。
2	出站适配器从中接收消息以执行所需操作的通道。
3	JPA 操作的实体类的完全限定名称。`entity-class`、`query` 和 `named-query` 属性是互斥的。可选。
4	用于执行 JPA 操作的 `jakarta.persistence.EntityManager` 实例。可选。
5	用于获取 `jakarta.persistence.EntityManager` 实例的 `jakarta.persistence.EntityManagerFactory` 实例，该实例执行 JPA 操作。可选。
6	用于执行 JPA 操作的 `org.springframework.integration.jpa.core.JpaOperations` 实现。我们建议不要提供您自己的实现，而是使用默认的 `org.springframework.integration.jpa.core.DefaultJpaOperations` 实现。您可以使用 `entity-manager`、`entity-manager-factory` 或 `jpa-operations` 属性中的任何一个。可选。
7	此适配器要执行的 JPA QL。可选。
8	此适配器需要执行的命名查询。可选。
9	此适配器要执行的原生查询。您可以使用 `jpa-query`、`named-query` 或 `native-query` 属性中的任何一个。可选。
10	当注册多个使用者时，此使用者的顺序，从而管理负载平衡和故障转移。默认为 `Ordered.LOWEST_PRECEDENCE`。可选。
11	用于获取 `o.s.i.jpa.support.parametersource.ParameterSource` 实例的 `o.s.i.jpa.support.parametersource.ParameterSourceFactory` 实例，该实例用于解析查询中参数的值。如果您使用 JPA 实体执行操作，则忽略此属性。`parameter` 子元素与 `parameter-source-factory` 属性互斥，必须在提供的 `ParameterSourceFactory` 上配置。可选。
12	接受以下值之一：`PERSIST`、`MERGE` 或 `DELETE`。指示适配器需要执行的操作。仅当您使用实体进行 JPA 操作时才相关。如果您提供 JPA QL、命名查询或原生查询，则忽略此属性。默认为 `MERGE`。可选。从 Spring Integration 3.0 开始，持久化或合并的有效负载也可以是 `java.lang.Iterable` 类型。在这种情况下，`Iterable` 返回的每个对象都被视为一个实体，并使用底层的 `EntityManager` 进行持久化或合并。迭代器返回的空值将被忽略。
13	如果要在持久化、合并或删除操作后立即刷新持久化上下文，并且不想依赖于 `EntityManager` 的 `flushMode`，则将此值设置为 `true`。默认为 `false`。仅当您未指定 `flush-size` 属性时才适用。如果将此属性设置为 `true`，则如果未配置其他值，则 `flush-size` 会隐式设置为 `1`。
14	如果要在持久化、合并或删除操作后立即刷新持久化上下文，并且不想依赖于 `EntityManager` 的 `flushMode`，则将此属性设置为大于 '0' 的值。默认值为 `0`，表示“不刷新”。此属性适用于具有 `Iterable` 有效负载的消息。例如，如果 `flush-size` 设置为 `3`，则在每三个实体之后调用 `entityManager.flush()`。此外，在整个循环结束后，还会再次调用 `entityManager.flush()`。如果使用大于 '0' 的值指定了 'flush-size' 属性，则无需配置 `flush` 属性。
15	如果要在每次刷新操作后立即清除持久化上下文，则将此值设置为 'true'。仅当 `flush` 属性设置为 `true` 或 `flush-size` 属性设置为大于 `0` 的值时，才会应用此属性的值。
16	如果设置为 `true`，则消息的有效负载将用作参数的来源。但是，如果设置为 `false`，则整个 `Message` 将可用作参数的来源。可选。
17	定义事务管理属性以及 JPA 适配器要使用的交易管理器的引用。可选。
18	一个或多个 `parameter` 属性，每个参数用于查询中的每个参数。计算参数的值时会计算值或表达式。可选。

使用 Java 配置进行配置

以下 Spring Boot 应用程序显示了如何使用 Java 配置出站适配器的示例

@SpringBootApplication
@EntityScan(basePackageClasses = StudentDomain.class)
@IntegrationComponentScan
public class JpaJavaApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder(JpaJavaApplication.class)
            .web(false)
            .run(args);
    }

    @Autowired
    private EntityManagerFactory entityManagerFactory;

    @MessagingGateway
    interface JpaGateway {

       @Gateway(requestChannel = "jpaPersistChannel")
       @Transactional
       void persistStudent(StudentDomain payload);

    }

    @Bean
    public JpaExecutor jpaExecutor() {
        JpaExecutor executor = new JpaExecutor(this.entityManagerFactory);
        jpaExecutor.setEntityClass(StudentDomain.class);
        jpaExecutor.setPersistMode(PersistMode.PERSIST);
        return executor;
    }

    @Bean
    @ServiceActivator(channel = "jpaPersistChannel")
    public MessageHandler jpaOutbound() {
        JpaOutboundGateway adapter = new JpaOutboundGateway(jpaExecutor());
        adapter.setProducesReply(false);
        return adapter;
    }

}

使用 Java DSL 进行配置

以下 Spring Boot 应用程序显示了如何使用 Java DSL 配置出站适配器的示例

@SpringBootApplication
@EntityScan(basePackageClasses = StudentDomain.class)
public class JpaJavaApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder(JpaJavaApplication.class)
            .web(false)
            .run(args);
    }

    @Autowired
    private EntityManagerFactory entityManagerFactory;

    @Bean
    public IntegrationFlow outboundAdapterFlow() {
        return f -> f
                .handle(Jpa.outboundAdapter(this.entityManagerFactory)
                                .entityClass(StudentDomain.class)
                                .persistMode(PersistMode.PERSIST),
                        e -> e.transactional());
    }

}