Hazelcast 支援

Spring Integration 提供通道適配器和其他實用元件，以與記憶體內資料網格 Hazelcast 互動。

您需要將此相依性包含到您的專案中

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.integration</groupId>
    <artifactId>spring-integration-hazelcast</artifactId>
    <version>6.3.5</version>
</dependency>
compile "org.springframework.integration:spring-integration-hazelcast:6.3.5"

Hazelcast 元件的 XML 命名空間和 schemaLocation 定義如下

xmlns:int-hazelcast="http://www.springframework.org/schema/integration/hazelcast"
xsi:schemaLocation="http://www.springframework.org/schema/integration/hazelcast
          https://www.springframework.org/schema/integration/hazelcast/spring-integration-hazelcast.xsd"

Hazelcast 事件驅動輸入通道適配器

Hazelcast 提供分散式資料結構，例如

  • com.hazelcast.map.IMap

  • com.hazelcast.multimap.MultiMap

  • com.hazelcast.collection.IList

  • com.hazelcast.collection.ISet

  • com.hazelcast.collection.IQueue

  • com.hazelcast.topic.ITopic

  • com.hazelcast.replicatedmap.ReplicatedMap

它也提供事件監聽器，以便監聽對這些資料結構所做的修改。

  • com.hazelcast.core.EntryListener<K, V>

  • com.hazelcast.collection.ItemListener

  • com.hazelcast.topic.MessageListener

Hazelcast 事件驅動輸入通道適配器監聽相關的快取事件，並將事件訊息傳送到定義的通道。它同時支援 XML 和 JavaConfig 驅動的設定。

XML 設定

<int-hazelcast:inbound-channel-adapter channel="mapChannel"
                      cache="map"
                      cache-events="UPDATED, REMOVED"
                      cache-listening-policy="SINGLE" />

Hazelcast 事件驅動輸入通道適配器需要以下屬性

  • channel：指定訊息傳送到的通道；

  • cache：指定要監聽的分散式物件參考。這是強制性屬性；

  • cache-events：指定要監聽的快取事件。這是可選屬性，預設值為 ADDED。其支援的值如下

  • IMap 和 MultiMap 支援的快取事件類型：ADDED、REMOVED、UPDATED、EVICTED、EVICT_ALL 和 CLEAR_ALL；

  • ReplicatedMap 支援的快取事件類型：ADDED、REMOVED、UPDATED、EVICTED；

  • IList、ISet 和 IQueue 支援的快取事件類型：ADDED、REMOVED。ITopic 沒有快取事件類型。

  • cache-listening-policy：指定快取監聽策略為 SINGLE 或 ALL。這是可選屬性，預設值為 SINGLE。每個監聽相同快取物件且具有相同 cache-events 屬性的 Hazelcast 輸入通道適配器，可以接收單一事件訊息或所有事件訊息。如果設定為 ALL，則所有監聽相同快取物件且具有相同 cache-events 屬性的 Hazelcast 輸入通道適配器，都將接收所有事件訊息。如果設定為 SINGLE，它們將接收唯一的事件訊息。

一些設定範例

分散式 Map
<int:channel id="mapChannel"/>

<int-hazelcast:inbound-channel-adapter channel="mapChannel"
                              cache="map"
                              cache-events="UPDATED, REMOVED" />

<bean id="map" factory-bean="instance" factory-method="getMap">
    <constructor-arg value="map"/>
</bean>

<bean id="instance" class="com.hazelcast.core.Hazelcast"
            factory-method="newHazelcastInstance">
    <constructor-arg>
        <bean class="com.hazelcast.config.Config" />
    </constructor-arg>
</bean>
分散式 MultiMap
<int-hazelcast:inbound-channel-adapter channel="multiMapChannel"
                              cache="multiMap"
                              cache-events="ADDED, REMOVED, CLEAR_ALL" />

<bean id="multiMap" factory-bean="instance" factory-method="getMultiMap">
    <constructor-arg value="multiMap"/>
</bean>
分散式 List
<int-hazelcast:inbound-channel-adapter  channel="listChannel"
                               cache="list"
                               cache-events="ADDED, REMOVED"
                               cache-listening-policy="ALL" />

<bean id="list" factory-bean="instance" factory-method="getList">
    <constructor-arg value="list"/>
</bean>
分散式 Set
<int-hazelcast:inbound-channel-adapter channel="setChannel" cache="set" />

<bean id="set" factory-bean="instance" factory-method="getSet">
    <constructor-arg value="set"/>
</bean>
分散式 Queue
<int-hazelcast:inbound-channel-adapter  channel="queueChannel"
                               cache="queue"
                               cache-events="REMOVED"
                               cache-listening-policy="ALL" />

<bean id="queue" factory-bean="instance" factory-method="getQueue">
    <constructor-arg value="queue"/>
</bean>
分散式 Topic
<int-hazelcast:inbound-channel-adapter channel="topicChannel" cache="topic" />

<bean id="topic" factory-bean="instance" factory-method="getTopic">
    <constructor-arg value="topic"/>
</bean>
Replicated Map
<int-hazelcast:inbound-channel-adapter channel="replicatedMapChannel"
                              cache="replicatedMap"
                              cache-events="ADDED, UPDATED, REMOVED"
                              cache-listening-policy="SINGLE"  />

<bean id="replicatedMap" factory-bean="instance" factory-method="getReplicatedMap">
    <constructor-arg value="replicatedMap"/>
</bean>

Java 設定範例

以下範例顯示 DistributedMap 設定。相同的設定可以用於其他分散式資料結構（IMap、MultiMap、ReplicatedMap、IList、ISet、IQueue 和 ITopic）

@Bean
public PollableChannel distributedMapChannel() {
    return new QueueChannel();
}

@Bean
public IMap<Integer, String> distributedMap() {
    return hazelcastInstance().getMap("Distributed_Map");
}

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public HazelcastEventDrivenMessageProducer hazelcastEventDrivenMessageProducer() {
    final HazelcastEventDrivenMessageProducer producer = new HazelcastEventDrivenMessageProducer(distributedMap());
    producer.setOutputChannel(distributedMapChannel());
    producer.setCacheEventTypes("ADDED,REMOVED,UPDATED,CLEAR_ALL");
    producer.setCacheListeningPolicy(CacheListeningPolicyType.SINGLE);

    return producer;
}

Hazelcast 連續查詢輸入通道適配器

Hazelcast 連續查詢啟用監聽對特定 Map 條目執行的修改。Hazelcast 連續查詢輸入通道適配器是一個事件驅動通道適配器，它根據定義的述詞監聽相關的分散式 Map 事件。

  • Java

  • XML

@Bean
public PollableChannel cqDistributedMapChannel() {
    return new QueueChannel();
}

@Bean
public IMap<Integer, String> cqDistributedMap() {
    return hazelcastInstance().getMap("CQ_Distributed_Map");
}

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public HazelcastContinuousQueryMessageProducer hazelcastContinuousQueryMessageProducer() {
    final HazelcastContinuousQueryMessageProducer producer =
        new HazelcastContinuousQueryMessageProducer(cqDistributedMap(), "surname=TestSurname");
    producer.setOutputChannel(cqDistributedMapChannel());
    producer.setCacheEventTypes("UPDATED");
    producer.setIncludeValue(false);

    return producer;
}
<int:channel id="cqMapChannel"/>

<int-hazelcast:cq-inbound-channel-adapter
                channel="cqMapChannel"
                cache="cqMap"
                cache-events="UPDATED, REMOVED"
                predicate="name=TestName AND surname=TestSurname"
                include-value="true"
                cache-listening-policy="SINGLE"/>

<bean id="cqMap" factory-bean="instance" factory-method="getMap">
    <constructor-arg value="cqMap"/>
</bean>

<bean id="instance" class="com.hazelcast.core.Hazelcast"
            factory-method="newHazelcastInstance">
    <constructor-arg>
        <bean class="com.hazelcast.config.Config" />
    </constructor-arg>
</bean>

它支援六個屬性，如下所示

  • channel：指定訊息傳送到的通道；

  • cache：指定要監聽的分散式 Map 參考。強制性；

  • cache-events：指定要監聽的快取事件。可選屬性，預設值為 ADDED。支援的值為 ADDED、REMOVED、UPDATED、EVICTED、EVICT_ALL 和 CLEAR_ALL；

  • predicate：指定一個述詞，以監聽對特定 Map 條目執行的修改。強制性；

  • include-value：指定在連續查詢結果中包含值和 oldValue。可選，預設值為 true；

  • cache-listening-policy：指定快取監聽策略為 SINGLE 或 ALL。可選，預設值為 SINGLE。每個監聽相同快取物件且具有相同 cache-events 屬性的 Hazelcast CQ 輸入通道適配器，可以接收單一事件訊息或所有事件訊息。如果設定為 ALL，則所有監聽相同快取物件且具有相同 cache-events 屬性的 Hazelcast CQ 輸入通道適配器，都將接收所有事件訊息。如果設定為 SINGLE，它們將接收唯一的事件訊息。

Hazelcast 叢集監視器輸入通道適配器

Hazelcast 叢集監視器支援監聽對叢集執行的修改。Hazelcast 叢集監視器輸入通道適配器是一個事件驅動通道適配器，它監聽相關的成員資格、分散式物件、移轉、生命週期和用戶端事件

  • Java

  • XML

@Bean
public PollableChannel eventChannel() {
    return new QueueChannel();
}

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public HazelcastClusterMonitorMessageProducer hazelcastClusterMonitorMessageProducer() {
    HazelcastClusterMonitorMessageProducer producer = new HazelcastClusterMonitorMessageProducer(hazelcastInstance());
    producer.setOutputChannel(eventChannel());
    producer.setMonitorEventTypes("DISTRIBUTED_OBJECT");

    return producer;
}
<int:channel id="monitorChannel"/>

<int-hazelcast:cm-inbound-channel-adapter
                 channel="monitorChannel"
                 hazelcast-instance="instance"
                 monitor-types="MEMBERSHIP, DISTRIBUTED_OBJECT" />

<bean id="instance" class="com.hazelcast.core.Hazelcast"
            factory-method="newHazelcastInstance">
    <constructor-arg>
        <bean class="com.hazelcast.config.Config" />
    </constructor-arg>
</bean>

它支援三個屬性，如下所示

  • channel：指定訊息傳送到的通道；

  • hazelcast-instance：指定要監聽叢集事件的 Hazelcast 執行個體參考。這是強制性屬性；

  • monitor-types：指定要監聽的監視器類型。這是可選屬性，預設值為 MEMBERSHIP。支援的值為 MEMBERSHIP、DISTRIBUTED_OBJECT、MIGRATION、LIFECYCLE、CLIENT。

Hazelcast 分散式 SQL 輸入通道適配器

Hazelcast 允許在分散式 Map 上執行分散式查詢。Hazelcast 分散式 SQL 輸入通道適配器是一個輪詢輸入通道適配器。它執行定義的 distributed-sql 命令，並根據迭代類型傳回結果。

  • Java

  • XML

@Bean
public PollableChannel dsDistributedMapChannel() {
    return new QueueChannel();
}

@Bean
public IMap<Integer, String> dsDistributedMap() {
    return hazelcastInstance().getMap("DS_Distributed_Map");
}

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
@InboundChannelAdapter(value = "dsDistributedMapChannel", poller = @Poller(maxMessagesPerPoll = "1"))
public HazelcastDistributedSQLMessageSource hazelcastDistributedSQLMessageSource() {
    final HazelcastDistributedSQLMessageSource messageSource =
        new HazelcastDistributedSQLMessageSource(dsDistributedMap(),
            "name='TestName' AND surname='TestSurname'");
    messageSource.setIterationType(DistributedSQLIterationType.ENTRY);

    return messageSource;
}
<int:channel id="dsMapChannel"/>

<int-hazelcast:ds-inbound-channel-adapter
            channel="dsMapChannel"
            cache="dsMap"
            iteration-type="ENTRY"
            distributed-sql="active=false OR age >= 25 OR name = 'TestName'">
    <int:poller fixed-delay="100"/>
</int-hazelcast:ds-inbound-channel-adapter>

<bean id="dsMap" factory-bean="instance" factory-method="getMap">
    <constructor-arg value="dsMap"/>
</bean>

<bean id="instance" class="com.hazelcast.core.Hazelcast"
            factory-method="newHazelcastInstance">
    <constructor-arg>
        <bean class="com.hazelcast.config.Config" />
    </constructor-arg>
</bean>

它需要一個 poller 並支援四個屬性

  • channel：指定訊息傳送到的通道。這是強制性屬性；

  • cache：指定要查詢的分散式 IMap 參考。這是強制性屬性；

  • iteration-type：指定結果類型。分散式 SQL 可以在 EntrySet、KeySet、LocalKeySet 或 Values 上執行。這是可選屬性，預設值為 VALUE。支援的值為 ENTRY、KEY、LOCAL_KEY 和 VALUE；

  • distributed-sql：指定 sql 語句的 where 子句。這是強制性屬性。

Hazelcast 輸出通道適配器

Hazelcast 輸出通道適配器監聽其定義的通道，並將傳入的訊息寫入相關的分散式快取。它需要 cache、cache-expression 或 HazelcastHeaders.CACHE_NAME 其中之一來定義分散式物件。支援的分散式物件包括：IMap、MultiMap、ReplicatedMap、IList、ISet、IQueue 和 ITopic。

  • Java

  • XML

@Bean
public MessageChannel distributedMapChannel() {
    return new DirectChannel();
}

@Bean
public IMap<Integer, String> distributedMap() {
    return hzInstance().getMap("Distributed_Map");
}

@Bean
public HazelcastInstance hzInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
@ServiceActivator(inputChannel = "distributedMapChannel")
public HazelcastCacheWritingMessageHandler hazelcastCacheWritingMessageHandler() {
    HazelcastCacheWritingMessageHandler handler = new HazelcastCacheWritingMessageHandler();
    handler.setDistributedObject(distributedMap());
    handler.setKeyExpression(new SpelExpressionParser().parseExpression("payload.id"));
    handler.setExtractPayload(true);
    return handler;
}
<int-hazelcast:outbound-channel-adapter channel="mapChannel"
                    cache-expression="headers['CACHE_HEADER']"
                    key-expression="payload.key"
                    extract-payload="true"/>

它需要以下屬性

  • channel：指定訊息傳送到的通道；

  • cache：指定分散式物件參考。可選；

  • cache-expression：透過 Spring 運算式語言 (SpEL) 指定分散式物件。可選；

  • key-expression：透過 Spring 運算式語言 (SpEL) 指定鍵值對的鍵。可選，僅適用於 IMap、MultiMap 和 ReplicatedMap 分散式資料結構。

  • extract-payload：指定是否傳送整個訊息或僅傳送酬載。可選屬性，預設值為 true。如果為 true，則只會將酬載寫入分散式物件。否則，將會轉換訊息標頭和酬載，並寫入整個訊息。

透過在標頭中設定分散式物件名稱，訊息可以透過相同的通道寫入不同的分散式物件。如果未定義 cache 或 cache-expression 屬性，則必須在請求 Message 中設定 HazelcastHeaders.CACHE_NAME 標頭。

Hazelcast 領導者選舉

如果需要領導者選舉（例如，對於高可用性訊息消費者，其中只有一個節點應該接收訊息），則可以使用基於 Hazelcast 的 LeaderInitiator

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public LeaderInitiator initiator() {
    return new LeaderInitiator(hazelcastInstance());
}

當節點被選為領導者時，它將向所有應用程式監聽器傳送 OnGrantedEvent。

Hazelcast 訊息儲存區

對於分散式訊息傳遞狀態管理，例如用於持久性 QueueChannel 或追蹤 Aggregator 訊息群組，提供了 HazelcastMessageStore 實作

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public MessageGroupStore messageStore() {
    return new HazelcastMessageStore(hazelcastInstance());
}

預設情況下，SPRING_INTEGRATION_MESSAGE_STORE IMap 用於將訊息和群組儲存為鍵/值。任何自訂 IMap 都可以提供給 HazelcastMessageStore。

Hazelcast 中繼資料儲存區

使用後端 Hazelcast IMap 實作了 ListenableMetadataStore。預設 Map 是以名稱 SPRING_INTEGRATION_METADATA_STORE 建立的，可以自訂。

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public MetadataStore metadataStore() {
    return new HazelcastMetadataStore(hazelcastInstance());
}

HazelcastMetadataStore 實作了 ListenableMetadataStore，允許您註冊自己的 MetadataStoreListener 類型監聽器，以透過 addListener(MetadataStoreListener callback) 監聽事件。

Hazelcast 鎖定登錄

使用後端 Hazelcast 分散式 ILock 支援實作了 LockRegistry

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance();
}

@Bean
public LockRegistry lockRegistry() {
    return new HazelcastLockRegistry(hazelcastInstance());
}

當與共用的 MessageGroupStore（例如，Aggregator 儲存區管理）一起使用時，HazelcastLockRegistry 可以用於在多個應用程式執行個體之間提供此功能，以便一次只有一個執行個體可以操作群組。

對於所有分散式操作，CP 子系統必須在 HazelcastInstance 上啟用。

使用 Hazelcast 的訊息通道

Hazelcast IQueue 和 ITopic 分散式物件本質上是訊息傳遞基本元素，可以在 Spring Integration 核心元件中使用，而無需此 Hazelcast 模組中的額外實作。

QueueChannel 可以由任何 java.util.Queue 提供，包括提到的 Hazelcast 分散式 IQueue

@Bean
PollableChannel hazelcastQueueChannel(HazelcastInstance hazelcastInstance) {
    return new QueueChannel(hazelcastInstance.getQueue("springIntegrationQueue"));
}

將此設定放置在應用程式 Hazelcast 叢集中的多個節點上，將使 QueueChannel 成為分散式，並且只有一個節點能夠從該 IQueue 輪詢單一 Message。這與 PollableJmsChannel、PollableKafkaChannel 或 PollableAmqpChannel 的運作方式類似。

如果生產者端不是 Spring Integration 應用程式，則無法設定 QueueChannel，因此使用純 Hazelcast IQueue API 來生產資料。在這種情況下，QueueChannel 方法在消費者端是錯誤的：必須改用 輸入通道適配器 解決方案

@Bean
public IQueue<String> myStringHzQueue(HazelcastInstance hazelcastInstance) {
    return hazelcastInstance.getQueue("springIntegrationQueue");
}

@Bean
@InboundChannelAdapter(channel = "stringValuesFromHzQueueChannel")
Supplier<String> fromHzIQueueSource(IQueue<String> myStringHzQueue) {
    return myStringHzQueue::poll;
}

Hazelcast 中的 ITopic 抽象概念與 JMS 中的 Topic 具有相似的語義：所有訂閱者都會收到發佈的訊息。透過一對簡單的 MessageChannel Bean，此機制作為開箱即用的功能受到支援

@Bean
public ITopic<Message<?>> springIntegrationTopic(HazelcastInstance hazelcastInstance,
        MessageChannel fromHazelcastTopicChannel) {

    ITopic<Message<?>> topic = hazelcastInstance.getTopic("springIntegrationTopic");
	topic.addMessageListener(m -> fromHazelcastTopicChannel.send(m.getMessageObject()));
	return topic;
}

@Bean
public MessageChannel publishToHazelcastTopicChannel(ITopic<Message<?>> springIntegrationTopic) {
    return new FixedSubscriberChannel(springIntegrationTopic::publish);
}

@Bean
public MessageChannel fromHazelcastTopicChannel() {
    return new DirectChannel();
}

FixedSubscriberChannel 是 DirectChannel 的最佳化變體，它需要在初始化時使用 MessageHandler。由於 MessageHandler 是一個函數介面，因此可以為 handleMessage 方法提供簡單的 Lambda。當訊息傳送到 publishToHazelcastTopicChannel 時，它只會發佈到 Hazelcast ITopic 上。com.hazelcast.topic.MessageListener 也是一個函數介面，因此可以為 ITopic#addMessageListener 提供 Lambda。因此，fromHazelcastTopicChannel 的訂閱者將會消耗傳送到提到的 ITopic 的所有訊息。

ExecutorChannel 可以與 IExecutorService 一起提供。例如，透過相關設定，可以實現叢集範圍的單例

@Bean
public HazelcastInstance hazelcastInstance() {
    return Hazelcast.newHazelcastInstance(
                new Config()
                    .addExecutorConfig(new ExecutorConfig()
                         .setName("singletonExecutor")
                         .setPoolSize(1)));
}

@Bean
public MessageChannel hazelcastSingletonExecutorChannel(HazelcastInstance hazelcastInstance) {
    return new ExecutorChannel(hazelcastInstance.getExecutorService("singletonExecutor"));
}