New API for the retries module

.changes/next-release/feature-AWSSDKforJavav2-b456b1c.json

@@ -0,0 +1,6 @@
+{
+    "category": "AWS SDK for Java v2", 
+    "contributor": "sugmanue", 
+    "type": "feature", 
+    "description": "Adds the new module retries API module"
+}

core/pom.xml

@@ -46,6 +46,7 @@
         <module>json-utils</module>
         <module>endpoints-spi</module>
         <module>imds</module>
+        <module>retries-api</module>
     </modules>
 
     <dependencyManagement>

core/retries-api/pom.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License").
+  ~ You may not use this file except in compliance with the License.
+  ~ A copy of the License is located at
+  ~
+  ~  http://aws.amazon.com/apache2.0
+  ~
+  ~ or in the "license" file accompanying this file. This file 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.
+  -->
+
+<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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>core</artifactId>
+        <groupId>software.amazon.awssdk</groupId>
+        <version>2.20.4-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>retries-api</artifactId>
+    <name>AWS Java SDK :: Retries API</name>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <configuration>
+                    <archive>
+                        <manifestEntries>
+                            <Automatic-Module-Name>software.amazon.awssdk.retries.api</Automatic-Module-Name>
+                        </manifestEntries>
+                    </archive>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>annotations</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>utils</artifactId>
+            <version>${awsjavasdk.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.hamcrest</groupId>
+            <artifactId>hamcrest-all</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/AcquireInitialTokenRequest.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Encapsulates the abstract scope to start the attempts about to be executed using a retry strategy.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface AcquireInitialTokenRequest {
+    /**
+     * An abstract scope for the attempts about to be executed.
+     *
+     * <p>A scope should be a unique string describing the smallest possible scope of failure for the attempts about to be
+     * executed. In practical terms, this is a key for the token bucket used to throttle request attempts. All attempts with the
+     * same scope share the same token bucket within the same {@link RetryStrategy}, ensuring that token-bucket throttling for
+     * requests against one resource do not result in throttling for requests against other, unrelated resources.
+     */
+    String scope();
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/AcquireInitialTokenResponse.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Encapsulates the response from the {@link RetryStrategy} to the request to start the attempts to be executed.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface AcquireInitialTokenResponse {
+    /**
+     * A {@link RetryToken} acquired by this invocation, used in subsequent {@link RetryStrategy#refreshRetryToken} or
+     * {@link RetryStrategy#recordSuccess} calls.
+     */
+    RetryToken token();
+
+    /**
+     * The amount of time to wait before performing the first attempt.
+     */
+    Duration delay();
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/BackoffStrategy.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Determines how long to wait before each execution attempt.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface BackoffStrategy {
+
+    /**
+     * Compute the amount of time to wait before the provided attempt number is executed.
+     *
+     * @param attempt The attempt to compute the delay for, starting at one.
+     * @throws IllegalArgumentException If the given attempt is less or equal to zero.
+     */
+    Duration computeDelay(int attempt);
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/RecordSuccessRequest.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Request that the calling code makes to the {@link RetryStrategy} using
+ * {@link RetryStrategy#recordSuccess(RecordSuccessRequest)} to notify that the attempted execution succeeded.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface RecordSuccessRequest {
+    /**
+     * A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
+     * {@link RetryStrategy#refreshRetryToken} call.
+     */
+    RetryToken token();
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/RecordSuccessResponse.java

@@ -0,0 +1,33 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Response given to the calling code by the {@link RetryStrategy} after calling
+ * {@link RetryStrategy#recordSuccess(RecordSuccessRequest)}.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface RecordSuccessResponse {
+    /**
+     * A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
+     * {@link RetryStrategy#refreshRetryToken} call.
+     */
+    RetryToken token();
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/RefreshRetryTokenRequest.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import java.time.Duration;
+import java.util.Optional;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Request that the calling code makes to the {@link RetryStrategy} using
+ * {@link RetryStrategy#refreshRetryToken(RefreshRetryTokenRequest)} to notify that the attempted execution failed and the
+ * {@link RetryToken} needs to be refreshed.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface RefreshRetryTokenRequest {
+    /**
+     * A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
+     * {@link RetryStrategy#refreshRetryToken} call.
+     */
+    RetryToken token();
+
+    /**
+     * A suggestion of how long to wait from the last attempt failure. For HTTP calls, this is usually extracted from a "retry
+     * after" header from the downstream service.
+     */
+    Optional<Duration> suggestedDelay();
+
+    /**
+     * The cause of the last attempt failure.
+     */
+    Throwable failure();
+}

core/retries-api/src/main/java/software/amazon/awssdk/retries/api/RefreshRetryTokenResponse.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file 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 software.amazon.awssdk.retries.api;
+
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.annotations.ThreadSafe;
+
+/**
+ * Response from the {@link RetryStrategy} after calling {@link RetryStrategy#refreshRetryToken(RefreshRetryTokenRequest)}.
+ */
+@SdkPublicApi
+@ThreadSafe
+public interface RefreshRetryTokenResponse {
+    /**
+     * A {@link RetryToken} acquired by this invocation, used in subsequent {@link RetryStrategy#refreshRetryToken} or
+     * {@link RetryStrategy#recordSuccess} calls.
+     */
+    RetryToken token();
+
+    /**
+     * The amount of time to wait before performing the next attempt.
+     */
+    Duration delay();
+}