java: refactor SR cluster management

.github/workflows/java-cm-integ-tests.yml

@@ -52,6 +52,8 @@ jobs:
 
     - name: Configure and run integration for cluster management
       working-directory: ./java/cluster_management
+      env:
+        IS_CI: "true"
       run: |
         mvn validate
         mvn initialize

java/cluster_management/README.md

@@ -2,23 +2,65 @@
 
 ## Overview
 
-The code examples in this topic show you how to use the Java PgJDBC to work with Aurora DSQL.
+The code examples in this topic show you how to use the AWS Java SDK v2 with DSQL
+to create, update, get, and delete single- and multi-Region clusters.
+
+Each file in the [/example](src/main/java/org/example) directory demonstrates a minimum
+working example for each operation. The `example()` method for each operation is invoked
+in [`DsqlClusterManagementTest.java`](src/test/java/org/example/DsqlClusterManagementTest.java).
 
 ## Run the examples
 
+### ⚠️ Important
+
+* Running this code might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the
+  minimum permissions required to perform the task. For more information, see
+  [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see
+  [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
 ### Prerequisites
 
-- java version >= 17 is needed
+- java version >= 17 is installed.
+- Valid AWS credentials can be discovered by the [default provider chain](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials-chain.html).
 
-### Run the example tests
+### Execute tests to create and delete clusters
+
+See [`DsqlClusterManagementTest.java`](src/test/java/org/example/DsqlClusterManagementTest.java) for configuration
+used in the `setup()` function.
 
 ```sh
-# Use the account credentials dedicated for javascript
-export CLUSTER_ENDPOINT="<your cluster endpoint>"
-export REGION="<your cluster region>"
+# Optional: Single-Region examples will execute in REGION_1. Defaults to 'us-east-1'.
+export REGION_1="us-east-1"
+
+# Optional: Multi-Region examples will create clusters in REGION_1 and REGION_2
+# with WITNESS_REGION as witness for both. Defaults to 'us-east-2' for REGION_2
+# and 'us-west-2' for WITNESS_REGION.
+export REGION_2="us-east-2"
+export WITNESS_REGION="us-west-2"
+
+# Will create, update, read, then delete clusters
 mvn test
 ```
 
+Test execution will take around five minutes as it waits for clusters to complete activation and deletion.
+
+### Executing single operations
+Files in [src/../example/](src/main/java/org/example) each have a `main()` method that let you exercise single operations.
+
+The build process will produce a single `.jar` that can be invoked as:
+```shell
+# Build the project if this has not been done yet with 'mvn test'
+mvn clean compile assembly:single
+
+# Check each operation for its expected environment variables
+REGION_1="us-east-1" CLUSTER_ID="<your cluster id>" \
+  java \
+  -cp target/AuroraDSQLClusterCrudExample-1.0-SNAPSHOT-jar-with-dependencies.jar \
+  org.example.GetCluster
+```
+
 ---
 
 Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

java/cluster_management/pom.xml

@@ -9,11 +9,10 @@
     <version>1.0-SNAPSHOT</version>
 
     <properties>
-        <maven.compiler.source>1.8</maven.compiler.source>
-        <maven.compiler.target>1.8</maven.compiler.target>
+        <maven.compiler.release>17</maven.compiler.release>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <mainClass>org.example.Example</mainClass>
-        <project.build.awssdk.version>2.29.27</project.build.awssdk.version>
+        <project.build.awssdk.version>2.31.41</project.build.awssdk.version>
     </properties>
 
     <dependencies>
@@ -26,21 +25,6 @@
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>dsql</artifactId>
-            <version>2.29.27</version> 
-        </dependency>
-        <dependency>
-            <groupId>software.amazon.awssdk</groupId>
-            <artifactId>regions</artifactId>
-            <version>${project.build.awssdk.version}</version>
-        </dependency>
-        <dependency>
-            <groupId>software.amazon.awssdk</groupId>
-            <artifactId>aws-core</artifactId>
-            <version>${project.build.awssdk.version}</version>
-        </dependency>
-        <dependency>
-            <groupId>software.amazon.awssdk</groupId>
-            <artifactId>aws-json-protocol</artifactId>
             <version>${project.build.awssdk.version}</version>
         </dependency>
         <dependency>
@@ -49,6 +33,12 @@
             <version>${project.build.awssdk.version}</version>
             <scope>compile</scope>
         </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-nop</artifactId>
+            <version>2.0.17</version>
+            <scope>runtime</scope>
+        </dependency>
     </dependencies>
 
     <build>
@@ -57,6 +47,11 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
                 <version>3.0.0-M5</version>
+                <configuration>
+                    <includes>
+                        <include>**/*Test.java</include>
+                    </includes>
+                </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -83,43 +78,19 @@
                     </arguments>
                 </configuration>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-                <version>3.1.0</version>
-                <configuration>
-                    <archive>
-                        <manifest>
-                            <addClasspath>true</addClasspath>
-                            <mainClass>org.example.Example</mainClass>
-                        </manifest>
-                    </archive>
-                </configuration>
-            </plugin>
-            <!-- Add the assemble plugin with standard configuration -->
             <plugin>
                 <artifactId>maven-assembly-plugin</artifactId>
                 <configuration>
                     <archive>
                         <manifest>
-                            <mainClass>org.example.Example</mainClass>
+                            <mainClass>${mainClass}</mainClass>
                         </manifest>
                     </archive>
                     <descriptorRefs>
                         <descriptorRef>jar-with-dependencies</descriptorRef>
                     </descriptorRefs>
                 </configuration>
             </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-surefire-plugin</artifactId>
-                <version>3.0.0-M5</version>
-                <configuration>
-                    <includes>
-                        <include>**/*Test.java</include>
-                    </includes>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 </project>

java/cluster_management/src/main/java/org/example/CreateCluster.java

@@ -1,53 +1,54 @@
 package org.example;
 
 import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
-import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
-import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
 import software.amazon.awssdk.regions.Region;
-import software.amazon.awssdk.retries.StandardRetryStrategy;
+import software.amazon.awssdk.retries.api.BackoffStrategy;
 import software.amazon.awssdk.services.dsql.DsqlClient;
-import software.amazon.awssdk.services.dsql.model.ClusterStatus;
 import software.amazon.awssdk.services.dsql.model.CreateClusterRequest;
 import software.amazon.awssdk.services.dsql.model.CreateClusterResponse;
+import software.amazon.awssdk.services.dsql.model.GetClusterResponse;
 
-import java.util.HashMap;
+import java.time.Duration;
 import java.util.Map;
 
 public class CreateCluster {
 
-    public static void main(String[] args) throws Exception {
-        Region region = Region.US_EAST_1;
-
-        ClientOverrideConfiguration clientOverrideConfiguration = ClientOverrideConfiguration.builder()
-                .retryStrategy(StandardRetryStrategy.builder().build())
-                .build();
-
-        DsqlClient client = DsqlClient.builder()
-                .httpClient(UrlConnectionHttpClient.create())
-                .overrideConfiguration(clientOverrideConfiguration)
-                .region(region)
-                .credentialsProvider(DefaultCredentialsProvider.create())
-                .build();
-
-        boolean deletionProtectionEnabled = true;
-        Map<String, String> tags = new HashMap<>();
-        tags.put("Name", "FooBar");
-
-        String identifier = createCluster(client, deletionProtectionEnabled, tags);
-        System.out.println("Cluster Id: " + identifier);
+    public static void main(String[] args) {
+        Region region = Region.of(System.getenv().getOrDefault("REGION_1", "us-east-1"));
+
+        try (
+                DsqlClient client = DsqlClient.builder()
+                        .region(region)
+                        .credentialsProvider(DefaultCredentialsProvider.create())
+                        .build()
+        ) {
+            GetClusterResponse cluster = example(client);
+            System.out.println("Created " + cluster);
+        }
     }
 
-    public static String createCluster(DsqlClient client, boolean deletionProtectionEnabled, Map<String, String> tags) throws Exception {
-        CreateClusterRequest createClusterRequest = CreateClusterRequest
-                .builder()
-                .deletionProtectionEnabled(deletionProtectionEnabled)
-                .tags(tags)
+    public static GetClusterResponse example(DsqlClient client) {
+        CreateClusterRequest request = CreateClusterRequest.builder()
+                .deletionProtectionEnabled(true)
+                .tags(Map.of(
+                        "Name", "java single region cluster",
+                        "Repo", "aws-samples/aurora-dsql-samples"
+                ))
                 .build();
-        CreateClusterResponse res = client.createCluster(createClusterRequest);
-        if (res.status() == ClusterStatus.CREATING) {
-            return res.identifier();
-        } else {
-            throw new Exception("Failed to create cluster");
-        }
+        CreateClusterResponse cluster = client.createCluster(request);
+        System.out.println("Created " + cluster.arn());
+
+        // The DSQL SDK offers a built-in waiter to poll for a cluster's
+        // transition to ACTIVE.
+        System.out.println("Waiting for cluster to become ACTIVE");
+        GetClusterResponse activeCluster = client.waiter().waitUntilClusterActive(
+                getCluster -> getCluster.identifier(cluster.identifier()),
+                config -> config.backoffStrategyV2(
+                        BackoffStrategy.fixedDelayWithoutJitter(Duration.ofSeconds(10))
+                ).waitTimeout(Duration.ofMinutes(5))
+        ).matched().response().orElseThrow();
+        System.out.println("Cluster is ACTIVE: " + activeCluster);
+
+        return activeCluster;
     }
 }