Add declarative Redis listener sample.

Author: christophstrobl

README.adoc

@@ -88,7 +88,8 @@ Contains also examples running on Virtual Threads.
 
 * `cluster` - Example for Redis Cluster support.
 * `example` - Example for basic Spring Data Redis setup.
-* `pubsub` - Example project to show Pub/Sub usage using Platform and Virtual Threads.
+* `listener` - Example to show declarative `@RedisListener` Pub/Sub.
+* `pubsub` - Example project to show programmatic Pub/Sub usage using Platform and Virtual Threads.
 * `reactive` - Example project to show reactive template support.
 * `repositories` - Example demonstrating Spring Data repository abstraction on top of Redis.
 * `sentinel` - Example for Redis Sentinel support.

redis/listener/README.md

@@ -0,0 +1,23 @@
+# Spring Data Redis - Annotated Listener Example
+
+This project demonstrates **declarative Redis Pub/Sub listeners**.
+
+## Features
+
+- `@RedisListener` on component methods to subscribe to Redis channels
+- `@EnableRedisListeners` to activate the listener infrastructure
+- Receiving **string** messages on a channel
+- Receiving **JSON** payloads deserialized to domain types (e.g. `Person`)
+
+## Requirements
+
+- **Docker** (for running integration tests with Testcontainers).
+
+## Running the tests
+
+Integration tests publish messages to Redis channels and assert that the annotated listeners receive and process them. They use Testcontainers to start a Redis container, so Docker must be running.
+
+```bash
+cd redis/listener
+mvn test
+```

redis/listener/pom.xml

@@ -0,0 +1,31 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<groupId>org.springframework.data.examples</groupId>
+		<artifactId>spring-data-redis-examples</artifactId>
+		<version>4.0.0-SNAPSHOT</version>
+		<relativePath>../pom.xml</relativePath>
+	</parent>
+
+	<artifactId>spring-data-redis-listener</artifactId>
+	<name>Spring Data Redis - Annotated Listener</name>
+	<description>Sample project for Spring Data Redis @RedisListener annotation-driven Pub/Sub</description>
+
+	<dependencies>
+
+		<dependency>
+			<groupId>org.springframework</groupId>
+			<artifactId>spring-messaging</artifactId>
+		</dependency>
+
+		<dependency>
+			<groupId>tools.jackson.core</groupId>
+			<artifactId>jackson-databind</artifactId>
+		</dependency>
+
+	</dependencies>
+
+</project>

redis/listener/src/main/java/example/springdata/redis/listener/Messages.java

@@ -0,0 +1,62 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.springdata.redis.listener;
+
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.LinkedBlockingQueue;
+
+/**
+ * Just a little helper to capture the already converted payload received from Redis Pub/Sub.
+ *
+ * @author Christoph Strobl
+ */
+public class Messages {
+
+	private final MessageCapturer<String> stringMessages = new MessageCapturer<>();
+	private final MessageCapturer<Person> pojoMessages = new MessageCapturer<>();
+
+	public BlockingQueue<String> capturedStrings() {
+		return stringMessages.captured();
+	}
+
+	void capture(Person person) {
+		pojoMessages.capture(person);
+	}
+
+	void capture(String string) {
+		stringMessages.capture(string);
+	}
+
+	public BlockingQueue<Person> capturedPojos() {
+		return pojoMessages.captured();
+	}
+
+	/**
+	 * Holder for received messages.
+	 */
+	public static class MessageCapturer<T> {
+
+		private final BlockingQueue<T> received = new LinkedBlockingQueue<>();
+
+		void capture(T message) {
+			received.add(message);
+		}
+
+		public BlockingQueue<T> captured() {
+			return received;
+		}
+	}
+}

redis/listener/src/main/java/example/springdata/redis/listener/Person.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.springdata.redis.listener;
+
+import java.util.Objects;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Example domain type for JSON payloads in Redis Pub/Sub messages.
+ *
+ * @author Christoph Strobl
+ */
+public class Person {
+
+	private final String firstname;
+	private final String lastname;
+
+	@JsonCreator
+	public Person(@JsonProperty("firstname") String firstname, @JsonProperty("lastname") String lastname) {
+		this.firstname = firstname;
+		this.lastname = lastname;
+	}
+
+	public String getFirstname() {
+		return firstname;
+	}
+
+	public String getLastname() {
+		return lastname;
+	}
+
+
+	@Override
+	public boolean equals(Object o) {
+		if (o == this) {
+			return true;
+		}
+		if (o == null || getClass() != o.getClass()) {
+			return false;
+		}
+		Person person = (Person) o;
+		return Objects.equals(firstname, person.firstname) && Objects.equals(lastname, person.lastname);
+	}
+
+	@Override
+	public int hashCode() {
+		return Objects.hash(firstname, lastname);
+	}
+
+	@Override
+	public String toString() {
+		return "Person{firstname='" + firstname + "', lastname='" + lastname + "'}";
+	}
+}

redis/listener/src/main/java/example/springdata/redis/listener/RedisListenerApplication.java

@@ -0,0 +1,101 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.springdata.redis.listener;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.Bean;
+import org.springframework.data.redis.annotation.EnableRedisListeners;
+import org.springframework.data.redis.annotation.RedisListener;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.listener.RedisMessageListenerContainer;
+import org.springframework.messaging.MessageHeaders;
+import org.springframework.messaging.handler.annotation.Payload;
+import org.springframework.stereotype.Component;
+
+/**
+ * Spring Boot application for the Redis annotated listener sample.
+ *
+ * @author Christoph Strobl
+ */
+@SpringBootApplication
+@EnableRedisListeners
+public class RedisListenerApplication {
+
+	public static void main(String[] args) {
+		SpringApplication.run(RedisListenerApplication.class, args);
+	}
+
+	/**
+	 * Compontent tying together declarative redis listeners and the capturing {@link Messages}
+	 * {@link RedisListenerApplication#messages() bean) that preserves received payload for verification in tests.
+	 */
+	@Component
+	static class Listeners {
+
+		private final Messages messages;
+
+		Listeners(@Autowired Messages messages) {
+			this.messages = messages;
+		}
+
+		/**
+		 * Declarative channel listener capturing raw {@link String}s received from Redis via the {@literal string-channel}.
+		 *
+		 * @param data the payload received via the {@literal string-channel}.
+		 * @param headers {@link MessageHeaders} when receiving the message.
+		 */
+		@RedisListener(topic = "string-channel")
+		public void processStringMessage(@Payload String data, MessageHeaders headers) {
+
+			System.out.printf("received message [%s] from [%s] at [%s].%n", data, headers.get("channel"), headers.getTimestamp());
+			messages.capture(data);
+		}
+
+		/**
+		 * Declarative channel listener capturing {@link Person} objects converted from JSON.
+		 *
+		 * @param person already converted {@link Person} object received from Redis via the {@literal person-channel}.
+		 */
+		@RedisListener(topic = "person-channel")
+		public void processPersonMessage(Person person) {
+			messages.capture(person);
+		}
+	}
+
+
+	@Bean
+	Messages messages() {
+		return new Messages();
+	}
+
+	/**
+	 * Provide required
+	 * {@link RedisMessageListenerContainer} for annotation-driven endpoints
+	 * {@link Listeners#processStringMessage(String, MessageHeaders)}} &
+	 * {@link Listeners#processPersonMessage(Person)}.
+	 *
+	 * @param connectionFactory must not be {@literal null}.
+	 * @return new instance of {@link RedisListenerApplication}.
+	 */
+	@Bean
+	public RedisMessageListenerContainer redisMessageListenerContainer(RedisConnectionFactory connectionFactory) {
+		RedisMessageListenerContainer container = new RedisMessageListenerContainer();
+		container.setConnectionFactory(connectionFactory);
+		return container;
+	}
+}

redis/listener/src/test/java/example/springdata/redis/listener/AnnotatedRedisListenerIntegrationTests.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2026-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package example.springdata.redis.listener;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.concurrent.TimeUnit;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.messaging.MessageHeaders;
+
+/**
+ * Integration tests for {@literal @RedisListener} annotation-driven endpoints.
+ *
+ * @author Christoph Strobl
+ */
+@SpringBootTest(classes = RedisListenerApplication.class)
+@Import(RedisTestConfiguration.class)
+class AnnotatedRedisListenerIntegrationTests {
+
+	@Autowired StringRedisTemplate redisTemplate;
+	@Autowired Messages messages;
+
+	/**
+	 * Publish a raw String message to the {@literal string-channel} channel and verify that the message
+	 * is received by the {@link RedisListenerApplication.Listeners#processStringMessage(String, MessageHeaders) string listener}.
+	 */
+	@Test
+	void shouldReceiveStringMessage() throws Exception {
+
+		redisTemplate.convertAndSend("string-channel", "Hello, world!");
+
+		String received = messages.capturedStrings().poll(5, TimeUnit.SECONDS);
+		assertThat(received).isEqualTo("Hello, world!");
+	}
+
+	/**
+	 * Publish a JSON String message to the {@literal person-channel} channel and verify that the payload is converted
+	 * and processed by the {@link RedisListenerApplication.Listeners#processPersonMessage(Person) person listener}.
+	 */
+	@Test
+	void shouldReceiveJsonPersonMessage() throws Exception {
+
+		String json = "{\"firstname\":\"Homer\",\"lastname\":\"Simpson\"}";
+		redisTemplate.convertAndSend("person-channel", json);
+
+		Person received = messages.capturedPojos().poll(5, TimeUnit.SECONDS);
+		assertThat(received).isNotNull();
+		assertThat(received.getFirstname()).isEqualTo("Homer");
+		assertThat(received.getLastname()).isEqualTo("Simpson");
+	}
+}