Prepare 3.1.2 release

.github/workflows/upload-docs.yml

@@ -29,12 +29,11 @@ jobs:
         with:
           candidate: java
           version: '17.0.1-tem'
-      - name: Set up JDK 8
-        uses: actions/setup-java@v4
+      - name: Set up JDK
+        uses: actions/setup-java@v1
         with:
           java-version: 8
-          distribution: 'adopt'
-          cache: 'maven'
+          jdkFile: ${{ steps.sdkman.outputs.file }}
       - uses: actions/cache@v1
         with:
           path: ~/.m2/repository

README.md

@@ -8,7 +8,7 @@ For a deep dive into the project, refer to the Spring Cloud AWS documentation:
 
 | Version                | Reference Docs                                                                                   | API Docs                                                                            |
 |------------------------|--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
-| Spring Cloud AWS 3.1.0 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.0/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.0/apidocs/index.html) | 
+| Spring Cloud AWS 3.1.1 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.1/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.1.1/apidocs/index.html) | 
 | Spring Cloud AWS 3.0.4 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.4/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/3.0.4/apidocs/index.html) | 
 | Spring Cloud AWS 2.4.4 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.4.4/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.4.4/apidocs/index.html) | 
 | Spring Cloud AWS 2.3.5 | [Reference Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.3.5/reference/html/index.html) | [API Docs](https://docs.awspring.io/spring-cloud-aws/docs/2.3.5/apidocs/index.html) |

docs/pom.xml

@@ -6,7 +6,7 @@
 	<parent>
 		<groupId>io.awspring.cloud</groupId>
 		<artifactId>spring-cloud-aws</artifactId>
-		<version>3.1.1</version>
+		<version>3.1.2</version>
 	</parent>
 	<artifactId>spring-cloud-aws-docs</artifactId>
 	<packaging>pom</packaging>

docs/src/main/asciidoc/_configprops.adoc

@@ -5,7 +5,8 @@
 |spring.cloud.aws.cloudwatch.region |  | Overrides the default region.
 |spring.cloud.aws.credentials.access-key |  | The access key to be used with a static provider.
 |spring.cloud.aws.credentials.instance-profile | `+++false+++` | Configures an instance profile credentials provider with no further configuration.
-|spring.cloud.aws.credentials.profile |  | The AWS profile.
+|spring.cloud.aws.credentials.profile.name |  | Profile name.
+|spring.cloud.aws.credentials.profile.path |  | Profile file path.
 |spring.cloud.aws.credentials.secret-key |  | The secret key to be used with a static provider.
 |spring.cloud.aws.credentials.sts.async-credentials-update | `+++false+++` | Enables provider to asynchronously fetch credentials in the background. Defaults to synchronous blocking if not specified otherwise.
 |spring.cloud.aws.credentials.sts.role-arn |  | ARN of IAM role associated with STS. If not provided this will be read from {@link software.amazon.awssdk.core.SdkSystemSetting}.
@@ -39,7 +40,8 @@
 |spring.cloud.aws.parameterstore.reload.period | `+++1m+++` | Refresh period for {@link PollingAwsPropertySourceChangeDetector}.
 |spring.cloud.aws.parameterstore.reload.strategy |  | Reload strategy to run when properties change.
 |spring.cloud.aws.region.instance-profile | `+++false+++` | Configures an instance profile region provider with no further configuration.
-|spring.cloud.aws.region.profile |  | The AWS profile.
+|spring.cloud.aws.region.profile.name |  | Profile name.
+|spring.cloud.aws.region.profile.path |  | Profile file path.
 |spring.cloud.aws.region.static |  | 
 |spring.cloud.aws.s3.accelerate-mode-enabled |  | Option to enable using the accelerate endpoint when accessing S3. Accelerate endpoints allow faster transfer of objects by using Amazon CloudFront's globally distributed edge locations.
 |spring.cloud.aws.s3.checksum-validation-enabled |  | Option to disable doing a validation of the checksum of an object stored in S3.
@@ -76,6 +78,7 @@
 |spring.cloud.aws.sqs.listener.max-concurrent-messages |  | The maximum concurrent messages that can be processed simultaneously for each queue. Note that if acknowledgement batching is being used, the actual maximum number of messages inflight might be higher.
 |spring.cloud.aws.sqs.listener.max-messages-per-poll |  | The maximum number of messages to be retrieved in a single poll to SQS.
 |spring.cloud.aws.sqs.listener.poll-timeout |  | The maximum amount of time for a poll to SQS.
+|spring.cloud.aws.sqs.queue-not-found-strategy |  | 
 |spring.cloud.aws.sqs.region |  | Overrides the default region.
 
 |===

docs/src/main/asciidoc/docker-compose.adoc

@@ -0,0 +1,34 @@
+[#spring-cloud-aws-docker-compose]
+== Docker Compose
+
+Spring Cloud AWS provides Docker Compose support for https://docs.localstack.cloud/references/docker-images/[LocalStack docker images] which simplifies local development of Spring Cloud AWS based projects.
+
+Maven coordinates, using <<index.adoc#bill-of-materials, Spring Cloud AWS BOM>>:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.awspring.cloud</groupId>
+    <artifactId>spring-cloud-aws-docker-compose</artifactId>
+</dependency>
+----
+
+For more information about Spring Docker Compose support please refer to https://docs.spring.io/spring-boot/reference/features/docker-compose.html[official Spring documentation]
+
+=== Example docker-compose.yaml file
+
+[source,yaml]
+----
+services:
+  localstack:
+    image: localstack/localstack
+    environment:
+      AWS_ACCESS_KEY_ID: noop
+      AWS_SECRET_ACCESS_KEY: noop
+      AWS_DEFAULT_REGION: eu-central-1
+    ports:
+      - "4566:4566"
+----
+
+`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_DEFAULT_REGION` are required environment variables to ensure proper integration.
+

docs/src/main/asciidoc/index.adoc

@@ -150,6 +150,12 @@ include::parameter-store.adoc[]
 
 include::cloudwatch.adoc[]
 
+include::spring-modulith.adoc[]
+
+include::testing.adoc[]
+
+include::docker-compose.adoc[]
+
 include::migration.adoc[]
 
 == Configuration properties

docs/src/main/asciidoc/s3.adoc

@@ -208,7 +208,7 @@ s3Template.upload(BUCKET, "file.txt", is, ObjectMetadata.builder().contentType("
 Another feature of `S3Template` is the ability to generate signed URLs for getting/putting S3 objects in a single method call.
 [source,java]
 ----
-URL signedGetUrl = s3Template.createSignedGetUrl("bucket_name", "file.txt", Duration.ofMinutes(5));
+URL signedGetUrl = s3Template.createSignedGetURL("bucket_name", "file.txt", Duration.ofMinutes(5));
 ----
 
 `S3Template` also allows storing & retrieving Java objects.

docs/src/main/asciidoc/spring-modulith.adoc

@@ -0,0 +1,34 @@
+[#spring-cloud-aws-modulith]
+== Spring Modulith Integration
+
+Spring Cloud AWS comes with externalized events
+
+Integration with https://spring.io/projects/spring-modulith[Spring Modulith] provides capability to send externalized events to SNS and SQS. Read more about externalizing events in https://docs.spring.io/spring-modulith/reference/events.html#externalization[Spring Modulith Reference Guide].
+
+=== SNS
+
+Maven coordinates, using <<index.adoc#bill-of-materials, Spring Cloud AWS BOM>>:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.awspring.cloud</groupId>
+    <artifactId>spring-cloud-aws-modulith-events-sns</artifactId>
+</dependency>
+----
+
+The logical routing key will be used as SNS message group id. When routing key is set, requires SNS to be configured as a FIFO topic with content based deduplication enabled.
+
+=== SQS
+
+Maven coordinates, using <<index.adoc#bill-of-materials, Spring Cloud AWS BOM>>:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.awspring.cloud</groupId>
+    <artifactId>spring-cloud-aws-modulith-events-sqs</artifactId>
+</dependency>
+----
+
+The logical routing key will be used as SQS message group id. When routing key is set, requires SQS queue to be configured as a FIFO queue.

docs/src/main/asciidoc/sqs.adoc

@@ -618,6 +618,9 @@ NOTE: Queues declared in the same annotation will share the container, though ea
 ===== SNS Messages
 
 Since 3.1.1, when receiving SNS messages through the `@SqsListener`, the message includes all attributes of the `SnsNotification`. To only receive need the `Message` part of the payload, you can utilize the `@SnsNotificationMessage` annotation.
+
+For handling individual message processing, the @SnsNotificationMessage annotation can be used in the following manner:
+
 [source, java]
 ----
 @SqsListener("my-queue")
@@ -626,6 +629,16 @@ public void listen(@SnsNotificationMessage Pojo pojo) {
 }
 ----
 
+For batch message processing, use the @SnsNotificationMessage annotation with a List<Pojo> parameter.
+
+[source, java]
+----
+@SqsListener("my-queue")
+public void listen(@SnsNotificationMessage List<Pojo> pojos) {
+	System.out.println(pojos.size());
+}
+----
+
 ===== 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.
@@ -677,6 +690,7 @@ AcknowledgementMode must be set to `MANUAL` (see <<Acknowledging Messages>>)
 - `BatchAcknowledgement` - provides methods for manually acknowledging partial or whole message batches for batch listeners.
 AcknowledgementMode must be set to `MANUAL` (see <<Acknowledging Messages>>)
 - `Visibility` - provides the `changeTo()` method that enables changing the message's visibility to the provided value.
+- `BatchVisibility` - provides `changeTo()` methods that enables changing partial or whole message batches visibility to the provided value.
 - `QueueAttributes` - provides queue attributes for the queue that received the message.
 See <<Retrieving Attributes from SQS>> for how to specify the queue attributes that will be fetched from `SQS`
 - `software.amazon.awssdk.services.sqs.model.Message` - provides the original `Message` from `SQS`
@@ -699,7 +713,7 @@ public void listen(Message<MyPojo> message, MyPojo pojo, MessageHeaders headers,
 }
 ----
 
-IMPORTANT: Batch listeners support a single `List<MyPojo>` and `List<Message<MyPojo>>` method arguments, and an optional `BatchAcknowledgement` or `AsyncBatchAcknowledgement` arguments.
+IMPORTANT: Batch listeners support a single `List<MyPojo>` and `List<Message<MyPojo>>` method arguments, and optional `BatchAcknowledgement` (or `AsyncBatchAcknowledgement`) and `BatchVisibility` arguments.
 `MessageHeaders` should be extracted from the `Message` instances through the `getHeaders()` method.
 
 ==== Batch Processing
@@ -711,7 +725,9 @@ When batch mode is enabled, the framework will serve the entire result of a poll
 If a value greater than 10 is provided for `maxMessagesPerPoll`, the result of multiple polls will be combined and up to the respective amount of messages will be served to the listener.
 
 To enable batch processing using `@SqsListener`, a single `List<MyPojo>` or `List<Message<MyPojo>>` method argument should be provided in the listener method.
-The listener method can also have an optional `BatchAcknowledgement` argument for `AcknowledgementMode.MANUAL`.
+The listener method can also have:
+- an optional `BatchAcknowledgement` argument for `AcknowledgementMode.MANUAL`
+- an optional `BatchVisibility` argument
 
 Alternatively, `SqsContainerOptions` can be set to `ListenerMode.BATCH` in the `SqsContainerOptions` in the factory or container.
 
@@ -786,6 +802,7 @@ The Spring Boot Starter for SQS provides the following auto-configuration proper
 | <<maxConcurrentMessages, `spring.cloud.aws.sqs.listener.max-inflight-messages-per-queue`>> | Maximum number of inflight messages per queue. | No | 10
 | <<maxMessagesPerPoll, `spring.cloud.aws.sqs.listener.max-messages-per-poll`>> | Maximum number of messages to be received per poll. | No | 10
 | <<pollTimeout, `spring.cloud.aws.sqs.listener.poll-timeout`>> | Maximum amount of time to wait for messages in a poll. | No | 10 seconds
+| `spring.cloud.aws.sqs.queue-not-found-strategy`  | The strategy to be used by SqsTemplate and SqsListeners when a queue does not exist. | No | CREATE
 |===
 
 
@@ -884,6 +901,12 @@ See <<Retrieving Attributes from SQS>>.
 |Configures the `MessageSystemAttribute` that will be retrieved from SQS for each message.
 See <<Retrieving Attributes from SQS>>.
 
+|`fifoBatchGroupingStrategy`
+|`PROCESS_MESSAGE_GROUPS_IN_PARALLEL_BATCHES`, `PROCESS_MULTIPLE_GROUPS_IN_SAME_BATCH`
+|`PROCESS_MESSAGE_GROUPS_IN_PARALLEL_BATCHES`
+|Specifies how messages from FIFO queues should be grouped when retrieved by the container when listener
+mode is `batch`. See <<FIFO Support>>.
+
 |`messageConverter`
 |`MessagingMessageConverter`
 |`SqsMessagingMessageConverter`
@@ -1029,10 +1052,9 @@ NOTE: Spring-managed `MessageListenerContainer` beans' lifecycle actions are alw
 
 * Messages are polled with a `receiveRequestAttemptId`, and the received batch of messages is split according to the message`s `MessageGroupId`.
 * Each message from a given group will then be processed in order, while each group is processed in parallel.
-* If processing fails for a message, the following messages from the same message group are discarded so they will be served again after their `message visibility`
-expires.
+* To receive messages from multiple groups in a `batch`, set `fifoBatchGroupingStrategy` to `PROCESS_MULTIPLE_GROUPS_IN_SAME_BATCH` in `SqsContainerOptions`.
+* If processing fails for a message, the following messages from the same message group are discarded so they will be served again after their `message visibility` expires.
 * Messages which were already successfully processed and acknowledged will not be served again.
-* If a `batch` listener is used, each message group from a poll will be served as a batch to the listener method.
 * `FIFO` queues also have different defaults for acknowledging messages, see <<Acknowledgement Defaults>> for more information.
 * If a `message visibility` is set through `@SqsListener` or `SqsContainerOptions`, visibility will be extended for all messages in the message group before each message is processed.
 

docs/src/main/asciidoc/testing.adoc

@@ -0,0 +1,53 @@
+[#testing]
+== Testing
+
+Spring Cloud AWS provides utilities for https://java.testcontainers.org/modules/localstack/[LocalStack Container] that simplify using Testcontainers LocalStack module with Spring Cloud AWS based projects.
+
+Maven coordinates, using <<index.adoc#bill-of-materials, Spring Cloud AWS BOM>>:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.awspring.cloud</groupId>
+    <artifactId>spring-cloud-aws-testcontainers</artifactId>
+</dependency>
+----
+
+== Service Connection
+
+https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.testing.testcontainers.service-connections[@ServiceConnection] for https://java.testcontainers.org/modules/localstack/[LocalStack Container] simplifies configuring Spring Cloud AWS based project to point to LocalStack instead of real AWS.
+
+Once Spring Cloud AWS detects in application test code a `LocalStackContainer` bean annotated with `@ServiceConnection`, it will automatically configure `region` and `credentials` to point to a LocalStack container.
+
+[source,java]
+----
+@Bean
+@ServiceConnection
+LocalStackContainer localStackContainer() {
+	return new LocalStackContainer(DockerImageName.parse("localstack/localstack:<version>"));
+}
+----
+
+To understand in depth how service connection works, follow https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.testing.testcontainers.service-connections[Spring Boot Reference Guide] on this topic.
+
+=== Using AWS Clients with LocalStack
+
+Spring Cloud AWS provides `LocalstackAwsClientFactory` that simplifies creating AWS clients pointing to LocalStack, when there is a need to configure an AWS client outside of Spring application context:
+
+[source,java]
+----
+@Testcontainers
+class LocalstackAwsClientFactoryTest {
+
+	@Container
+	private LocalStackContainer localStackContainer = new LocalStackContainer(
+			DockerImageName.parse("localstack/localstack:3.2.0"));
+
+	@Test
+	void aTest() {
+		LocalstackAwsClientFactory factory = new LocalstackAwsClientFactory(localStackContainer);
+		S3Client s3Client = factory.create(S3Client.builder());
+		// ...
+	}
+}
+----

pom.xml

@@ -12,7 +12,7 @@
 
 	<groupId>io.awspring.cloud</groupId>
 	<artifactId>spring-cloud-aws</artifactId>
-	<version>3.1.1</version>
+	<version>3.1.2</version>
 	<packaging>pom</packaging>
 	<name>Spring Cloud AWS</name>
 
@@ -37,13 +37,15 @@
 		<module>spring-cloud-aws-core</module>
 		<module>spring-cloud-aws-autoconfigure</module>
 		<module>spring-cloud-aws-dependencies</module>
+		<module>spring-cloud-aws-docker-compose</module>
 		<module>spring-cloud-aws-parameter-store</module>
 		<module>spring-cloud-aws-secrets-manager</module>
 		<module>spring-cloud-aws-ses</module>
 		<module>spring-cloud-aws-sns</module>
 		<module>spring-cloud-aws-sqs</module>
 		<module>spring-cloud-aws-dynamodb</module>
-		<module>spring-cloud-aws-s3-parent</module>
+		<module>spring-cloud-aws-s3</module>
+		<module>spring-cloud-aws-testcontainers</module>
 		<module>spring-cloud-aws-starters/spring-cloud-aws-starter</module>
 		<module>spring-cloud-aws-starters/spring-cloud-aws-starter-dynamodb</module>
 		<module>spring-cloud-aws-starters/spring-cloud-aws-starter-metrics</module>
@@ -55,6 +57,7 @@
 		<module>spring-cloud-aws-starters/spring-cloud-aws-starter-sqs</module>
 		<module>spring-cloud-aws-samples</module>
 		<module>spring-cloud-aws-test</module>
+		<module>spring-cloud-aws-modulith</module>
 		<module>docs</module>
 	</modules>
 

spring-cloud-aws-autoconfigure/pom.xml

@@ -7,7 +7,7 @@
 	<parent>
 		<groupId>io.awspring.cloud</groupId>
 		<artifactId>spring-cloud-aws</artifactId>
-		<version>3.1.1</version>
+		<version>3.1.2</version>
 	</parent>
 
 	<artifactId>spring-cloud-aws-autoconfigure</artifactId>
@@ -90,13 +90,8 @@
 			<optional>true</optional>
 		</dependency>
 		<dependency>
-			<groupId>software.amazon.awssdk.crt</groupId>
-			<artifactId>aws-crt</artifactId>
-			<optional>true</optional>
-		</dependency>
-		<dependency>
-			<groupId>io.awspring.cloud</groupId>
-			<artifactId>spring-cloud-aws-s3-cross-region-client</artifactId>
+			<groupId>software.amazon.awssdk</groupId>
+			<artifactId>aws-crt-client</artifactId>
 			<optional>true</optional>
 		</dependency>
 		<dependency>