feat: add SNS notification resolver to SQS module (#1419)

Author: chomatdam

docs/src/main/asciidoc/sqs.adoc

@@ -694,6 +694,20 @@ public void listen(@SnsNotificationSubject String subject, @SnsNotificationMessa
 }
 ----
 
+Since 3.4.1, the complete SNS notification can be received with all its metadata using the `SnsNotification<T>` wrapper class. This provides access to both the message payload and all the metadata such as messageId, topicArn, subject, timestamp, and message attributes.
+
+[source, java]
+----
+@SqsListener("my-queue")
+public void listen(SnsNotification<Pojo> notification) {
+    String messageId = notification.getMessageId();
+    String topicArn = notification.getTopicArn();
+    notification.getSubject().ifPresent(subject -> System.out.println("Subject: " + subject));
+    Pojo message = notification.getMessage();
+    System.out.println("Message from topic " + topicArn + " with ID " + messageId + ": " + message);
+}
+----
+
 ===== Specifying a MessageListenerContainerFactory
 A `MessageListenerContainerFactory` can be specified through the `factory` property.
 Such factory will then be used to create the container for the annotated method.
@@ -738,6 +752,8 @@ A number of possible argument types are allowed in the listener method's signatu
 - `Message<MyPojo>` - Provides a `Message<MyPojo>` instance with the deserialized payload and `MessageHeaders`.
 - `List<MyPojo>` - Enables batch mode and receives the batch that was polled from SQS.
 - `List<Message<MyPojo>>` - Enables batch mode and receives the batch that was polled from SQS along with headers.
+- `SnsNotification<MyPojo>` - Provides access to both the message payload and all the metadata of an SNS notification.
+See <<SNS Messages>> for more information.
 - `@Header(String headerName)` - provides the specified header.
 - `@Headers` - provides the `MessageHeaders` or a `Map<String, Object>`
 - `Acknowledgement` - provides methods for manually acknowledging messages for single message listeners.
@@ -1948,7 +1964,7 @@ SqsListenerObservation.Convention sqsListenerObservationConvention() {
                    .and("messaging.operation", "receive")
                    .and("custom.tag", "custom-value");
         }
-        
+
         @Override
         public KeyValues getHighCardinalityKeyValues(SqsListenerObservation.Context context) {
             String paymentId = MessageHeaderUtils.getHeaderAsString(context.getMessage(), "payment-id-header-name");

spring-cloud-aws-samples/spring-cloud-aws-sqs-sample/src/main/java/io/awspring/cloud/sqs/sample/SnsNotificationSample.java

@@ -0,0 +1,96 @@
+/*
+ * Copyright 2013-2025 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 io.awspring.cloud.sqs.sample;
+
+import io.awspring.cloud.sqs.annotation.SqsListener;
+import io.awspring.cloud.sqs.operations.SqsTemplate;
+import io.awspring.cloud.sqs.support.converter.SnsNotification;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.context.annotation.Bean;
+import org.springframework.stereotype.Component;
+
+/**
+ * Sample demonstrating how to receive SNS notifications from SQS.
+ *
+ * @author Damien Chomat
+ */
+@Component
+public class SnsNotificationSample {
+
+	private static final Logger LOGGER = LoggerFactory.getLogger(SnsNotificationSample.class);
+
+	/**
+	 * Receives SNS notifications from the "sns-notification-custom-queue" SQS queue. The message payload is
+	 * automatically converted to a CustomMessage object.
+	 *
+	 * @param notification the SNS notification wrapper containing the message and metadata
+	 */
+	@SqsListener("sns-notification-custom-queue")
+	public void receiveCustomMessage(SnsNotification<CustomMessage> notification) {
+		LOGGER.info("Received SNS notification with ID: {}", notification.getMessageId());
+		LOGGER.info("From topic: {}", notification.getTopicArn());
+		notification.getSubject().ifPresent(subject -> LOGGER.info("Subject: {}", subject));
+
+		CustomMessage message = notification.getMessage();
+		LOGGER.info("Message content: {}", message.content());
+		LOGGER.info("Message timestamp: {}", message.timestamp());
+
+		LOGGER.info("Notification timestamp: {}", notification.getTimestamp());
+		LOGGER.info("Message attributes: {}", notification.getMessageAttributes());
+	}
+
+	/**
+	 * ApplicationRunner to send sample SNS messages to the queues for demonstration purposes. This simulates SNS
+	 * notifications being sent to SQS queues that are subscribed to SNS topics.
+	 */
+	@Bean
+	public ApplicationRunner sendSnsNotificationMessage(SqsTemplate sqsTemplate) {
+		return args -> {
+			// Simulate an SNS notification for an order processing topic
+			String orderNotificationMessage = """
+					{
+						"Type": "Notification",
+						"MessageId": "order-12345-notification",
+						"TopicArn": "arn:aws:sns:us-east-1:123456789012:order-processing-topic",
+						"Subject": "Order Processing Update",
+						"Message": "{\\"content\\": \\"Order #12345 has been processed successfully\\", \\"timestamp\\": 1672531200000}",
+						"Timestamp": "2023-01-01T12:00:00Z",
+						"MessageAttributes": {
+							"eventType": {
+								"Type": "String",
+								"Value": "ORDER_PROCESSED"
+							},
+							"priority": {
+								"Type": "String",
+								"Value": "high"
+							}
+						}
+					}
+					""";
+
+			LOGGER.info("Sending SNS notification messages to subscribed SQS queue...");
+			sqsTemplate.send("sns-notification-custom-queue", orderNotificationMessage);
+		};
+	}
+
+	/**
+	 * A custom message record for demonstration purposes.
+	 */
+	public record CustomMessage(String content, long timestamp) {
+	}
+}

spring-cloud-aws-samples/spring-cloud-aws-sqs-sample/src/main/java/io/awspring/cloud/sqs/sample/SpringSqsHandlerSample.java

@@ -25,8 +25,8 @@
 import org.springframework.context.annotation.Configuration;
 
 /**
- * Sample class to demonstrate how to handle multiple message types in a single listener
- * with {@link SqsHandler} annotation.
+ * Sample class to demonstrate how to handle multiple message types in a single listener with {@link SqsHandler}
+ * annotation.
  *
  * @author José Iêdo
  */
@@ -37,8 +37,12 @@ public class SpringSqsHandlerSample {
 	public static final String QUEUE_NAME = "multi-method-queue";
 	private static final Logger LOGGER = LoggerFactory.getLogger(SpringSqsHandlerSample.class);
 
-	private interface BaseMessage { }
-	private record SampleRecord(String propertyOne, String propertyTwo) { }
+	private interface BaseMessage {
+	}
+
+	private record SampleRecord(String propertyOne, String propertyTwo) {
+	}
+
 	private record AnotherSampleRecord(String propertyOne, String propertyTwo) implements BaseMessage { }
 
 	@SqsHandler
@@ -56,7 +60,6 @@ void handleMessage(Object message) {
 		LOGGER.info("Received message of type Object: {}", message);
 	}
 
-
 	@Bean
 	public ApplicationRunner sendMessageToQueueWithMultipleHandlers(SqsTemplate sqsTemplate) {
 		return args -> {

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/annotation/SqsHandler.java

@@ -29,8 +29,8 @@
  * <p>
  * Each payload type must have exactly one corresponding method.
  * <p>
- * If no method matches the payload type, a method marked as the default (using {@code isDefault = true}) will be invoked.
- * Only one method can be designated as the default.
+ * If no method matches the payload type, a method marked as the default (using {@code isDefault = true}) will be
+ * invoked. Only one method can be designated as the default.
  *
  * @author José Iêdo
  */
@@ -41,8 +41,8 @@
 public @interface SqsHandler {
 
 	/**
-	 * Indicates whether this method should be used as the default fallback method if no other {@link SqsHandler}
-	 * method matches the payload type.
+	 * Indicates whether this method should be used as the default fallback method if no other {@link SqsHandler} method
+	 * matches the payload type.
 	 *
 	 * @return {@code true} if this is the default method, {@code false} otherwise
 	 */

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/annotation/SqsListenerAnnotationBeanPostProcessor.java

@@ -25,6 +25,7 @@
 import io.awspring.cloud.sqs.support.resolver.NotificationMessageArgumentResolver;
 import io.awspring.cloud.sqs.support.resolver.NotificationSubjectArgumentResolver;
 import io.awspring.cloud.sqs.support.resolver.QueueAttributesMethodArgumentResolver;
+import io.awspring.cloud.sqs.support.resolver.SnsNotificationArgumentResolver;
 import io.awspring.cloud.sqs.support.resolver.SqsMessageMethodArgumentResolver;
 import io.awspring.cloud.sqs.support.resolver.VisibilityHandlerMethodArgumentResolver;
 import java.lang.reflect.Method;
@@ -110,6 +111,7 @@ protected Collection<HandlerMethodArgumentResolver> createAdditionalArgumentReso
 		if (objectMapper != null) {
 			argumentResolvers.add(new NotificationMessageArgumentResolver(messageConverter, objectMapper));
 			argumentResolvers.add(new NotificationSubjectArgumentResolver(objectMapper));
+			argumentResolvers.add(new SnsNotificationArgumentResolver(messageConverter, objectMapper));
 		}
 		return argumentResolvers;
 	}

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/config/MultiMethodSqsEndpoint.java

@@ -140,7 +140,8 @@ public <T> void setupContainer(MessageListenerContainer<T> container) {
 		container.setMessageListener(createMessageListenerInstance(compositeInvocableHandler));
 	}
 
-	protected <T> MessageListener<T> createMessageListenerInstance(CompositeInvocableHandler compositeInvocableHandler) {
+	protected <T> MessageListener<T> createMessageListenerInstance(
+			CompositeInvocableHandler compositeInvocableHandler) {
 		return new MessagingMessageListenerAdapter<>(compositeInvocableHandler);
 	}
 }