Skip to content

Commit 7ef8830

Browse files
sugmanuesugmanue
authored
New API for the retries module (#3769)
This new module includes the interfaces and classes that will be used to implement the new retry logic within the SDK.
1 parent c166bd3 commit 7ef8830

File tree

15 files changed

+813
-0
lines changed

15 files changed

+813
-0
lines changed

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"category": "AWS SDK for Java v2",
3+
"contributor": "sugmanue",
4+
"type": "feature",
5+
"description": "Adds the new module retries API module"
6+
}

‎core/pom.xml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@
4646
<module>json-utils</module>
4747
<module>endpoints-spi</module>
4848
<module>imds</module>
49+
<module>retries-api</module>
4950
</modules>
5051

5152
<dependencyManagement>

‎core/retries-api/pom.xml

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
~ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
4+
~
5+
~ Licensed under the Apache License, Version 2.0 (the "License").
6+
~ You may not use this file except in compliance with the License.
7+
~ A copy of the License is located at
8+
~
9+
~ http://aws.amazon.com/apache2.0
10+
~
11+
~ or in the "license" file accompanying this file. This file is distributed
12+
~ on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
13+
~ express or implied. See the License for the specific language governing
14+
~ permissions and limitations under the License.
15+
-->
16+
17+
<project xmlns="http://maven.apache.org/POM/4.0.0"
18+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
19+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
20+
<parent>
21+
<artifactId>core</artifactId>
22+
<groupId>software.amazon.awssdk</groupId>
23+
<version>2.20.4-SNAPSHOT</version>
24+
</parent>
25+
<modelVersion>4.0.0</modelVersion>
26+
27+
<artifactId>retries-api</artifactId>
28+
<name>AWS Java SDK :: Retries API</name>
29+
<build>
30+
<plugins>
31+
<plugin>
32+
<groupId>org.apache.maven.plugins</groupId>
33+
<artifactId>maven-jar-plugin</artifactId>
34+
<configuration>
35+
<archive>
36+
<manifestEntries>
37+
<Automatic-Module-Name>software.amazon.awssdk.retries.api</Automatic-Module-Name>
38+
</manifestEntries>
39+
</archive>
40+
</configuration>
41+
</plugin>
42+
</plugins>
43+
</build>
44+
45+
<dependencies>
46+
<dependency>
47+
<groupId>software.amazon.awssdk</groupId>
48+
<artifactId>annotations</artifactId>
49+
<version>${awsjavasdk.version}</version>
50+
</dependency>
51+
<dependency>
52+
<groupId>software.amazon.awssdk</groupId>
53+
<artifactId>utils</artifactId>
54+
<version>${awsjavasdk.version}</version>
55+
</dependency>
56+
<dependency>
57+
<groupId>org.junit.jupiter</groupId>
58+
<artifactId>junit-jupiter</artifactId>
59+
<version>${junit5.version}</version>
60+
<scope>test</scope>
61+
</dependency>
62+
<dependency>
63+
<groupId>org.hamcrest</groupId>
64+
<artifactId>hamcrest-all</artifactId>
65+
<scope>test</scope>
66+
</dependency>
67+
</dependencies>
68+
</project>

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
import software.amazon.awssdk.annotations.ThreadSafe;
20+
21+
/**
22+
* Encapsulates the abstract scope to start the attempts about to be executed using a retry strategy.
23+
*/
24+
@SdkPublicApi
25+
@ThreadSafe
26+
public interface AcquireInitialTokenRequest {
27+
/**
28+
* An abstract scope for the attempts about to be executed.
29+
*
30+
* <p>A scope should be a unique string describing the smallest possible scope of failure for the attempts about to be
31+
* executed. In practical terms, this is a key for the token bucket used to throttle request attempts. All attempts with the
32+
* same scope share the same token bucket within the same {@link RetryStrategy}, ensuring that token-bucket throttling for
33+
* requests against one resource do not result in throttling for requests against other, unrelated resources.
34+
*/
35+
String scope();
36+
}

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import java.time.Duration;
19+
import software.amazon.awssdk.annotations.SdkPublicApi;
20+
import software.amazon.awssdk.annotations.ThreadSafe;
21+
22+
/**
23+
* Encapsulates the response from the {@link RetryStrategy} to the request to start the attempts to be executed.
24+
*/
25+
@SdkPublicApi
26+
@ThreadSafe
27+
public interface AcquireInitialTokenResponse {
28+
/**
29+
* A {@link RetryToken} acquired by this invocation, used in subsequent {@link RetryStrategy#refreshRetryToken} or
30+
* {@link RetryStrategy#recordSuccess} calls.
31+
*/
32+
RetryToken token();
33+
34+
/**
35+
* The amount of time to wait before performing the first attempt.
36+
*/
37+
Duration delay();
38+
}

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import java.time.Duration;
19+
import software.amazon.awssdk.annotations.SdkPublicApi;
20+
import software.amazon.awssdk.annotations.ThreadSafe;
21+
22+
/**
23+
* Determines how long to wait before each execution attempt.
24+
*/
25+
@SdkPublicApi
26+
@ThreadSafe
27+
public interface BackoffStrategy {
28+
29+
/**
30+
* Compute the amount of time to wait before the provided attempt number is executed.
31+
*
32+
* @param attempt The attempt to compute the delay for, starting at one.
33+
* @throws IllegalArgumentException If the given attempt is less or equal to zero.
34+
*/
35+
Duration computeDelay(int attempt);
36+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
import software.amazon.awssdk.annotations.ThreadSafe;
20+
21+
/**
22+
* Request that the calling code makes to the {@link RetryStrategy} using
23+
* {@link RetryStrategy#recordSuccess(RecordSuccessRequest)} to notify that the attempted execution succeeded.
24+
*/
25+
@SdkPublicApi
26+
@ThreadSafe
27+
public interface RecordSuccessRequest {
28+
/**
29+
* A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
30+
* {@link RetryStrategy#refreshRetryToken} call.
31+
*/
32+
RetryToken token();
33+
}

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import software.amazon.awssdk.annotations.SdkPublicApi;
19+
import software.amazon.awssdk.annotations.ThreadSafe;
20+
21+
/**
22+
* Response given to the calling code by the {@link RetryStrategy} after calling
23+
* {@link RetryStrategy#recordSuccess(RecordSuccessRequest)}.
24+
*/
25+
@SdkPublicApi
26+
@ThreadSafe
27+
public interface RecordSuccessResponse {
28+
/**
29+
* A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
30+
* {@link RetryStrategy#refreshRetryToken} call.
31+
*/
32+
RetryToken token();
33+
}

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

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import java.time.Duration;
19+
import java.util.Optional;
20+
import software.amazon.awssdk.annotations.SdkPublicApi;
21+
import software.amazon.awssdk.annotations.ThreadSafe;
22+
23+
/**
24+
* Request that the calling code makes to the {@link RetryStrategy} using
25+
* {@link RetryStrategy#refreshRetryToken(RefreshRetryTokenRequest)} to notify that the attempted execution failed and the
26+
* {@link RetryToken} needs to be refreshed.
27+
*/
28+
@SdkPublicApi
29+
@ThreadSafe
30+
public interface RefreshRetryTokenRequest {
31+
/**
32+
* A {@link RetryToken} acquired a previous {@link RetryStrategy#acquireInitialToken} or
33+
* {@link RetryStrategy#refreshRetryToken} call.
34+
*/
35+
RetryToken token();
36+
37+
/**
38+
* A suggestion of how long to wait from the last attempt failure. For HTTP calls, this is usually extracted from a "retry
39+
* after" header from the downstream service.
40+
*/
41+
Optional<Duration> suggestedDelay();
42+
43+
/**
44+
* The cause of the last attempt failure.
45+
*/
46+
Throwable failure();
47+
}

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

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License").
5+
* You may not use this file except in compliance with the License.
6+
* A copy of the License is located at
7+
*
8+
* http://aws.amazon.com/apache2.0
9+
*
10+
* or in the "license" file accompanying this file. This file is distributed
11+
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12+
* express or implied. See the License for the specific language governing
13+
* permissions and limitations under the License.
14+
*/
15+
16+
package software.amazon.awssdk.retries.api;
17+
18+
import java.time.Duration;
19+
import software.amazon.awssdk.annotations.SdkPublicApi;
20+
import software.amazon.awssdk.annotations.ThreadSafe;
21+
22+
/**
23+
* Response from the {@link RetryStrategy} after calling {@link RetryStrategy#refreshRetryToken(RefreshRetryTokenRequest)}.
24+
*/
25+
@SdkPublicApi
26+
@ThreadSafe
27+
public interface RefreshRetryTokenResponse {
28+
/**
29+
* A {@link RetryToken} acquired by this invocation, used in subsequent {@link RetryStrategy#refreshRetryToken} or
30+
* {@link RetryStrategy#recordSuccess} calls.
31+
*/
32+
RetryToken token();
33+
34+
/**
35+
* The amount of time to wait before performing the next attempt.
36+
*/
37+
Duration delay();
38+
}

0 commit comments

Comments
 (0)