Implement Asynchronous EC2 Metadata Client

.changes/next-release/feature-AWSSDKforJavav2-4a07ee0.json

@@ -0,0 +1,6 @@
+{
+    "type": "feature",
+    "category": "AWS SDK for Java v2",
+    "contributor": "L-Applin",
+    "description": "EC2Metadata Asynchronous Client"
+}

core/imds/pom.xml

@@ -58,7 +58,7 @@
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>url-connection-client</artifactId>
             <version>${awsjavasdk.version}</version>
-            <scope>compile</scope>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
@@ -114,7 +114,7 @@
         </dependency>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
-            <artifactId>apache-client</artifactId>
+            <artifactId>netty-nio-client</artifactId>
             <version>${awsjavasdk.version}</version>
             <scope>test</scope>
         </dependency>

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataAsyncClient.java

@@ -0,0 +1,81 @@
+/*
+ * 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.imds;
+
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ScheduledExecutorService;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
+import software.amazon.awssdk.imds.internal.DefaultEc2MetadataAsyncClient;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+/**
+ * Interface to represent the Ec2Metadata Client Class. Used to access instance metadata from a running instance.
+ */
+@SdkPublicApi
+public interface Ec2MetadataAsyncClient extends SdkAutoCloseable {
+
+    /**
+     * Gets the specified instance metadata value by the given path.
+     *
+     * @param path Input path
+     * @return A CompletableFuture that completes when the MetadataResponse is made available.
+     */
+    CompletableFuture<MetadataResponse> get(String path);
+
+    /**
+     * Create an {@link Ec2MetadataAsyncClient} instance using the default values.
+     *
+     * @return
+     */
+    static Ec2MetadataAsyncClient create() {
+        return builder().build();
+    }
+
+    static Ec2MetadataAsyncClient.Builder builder() {
+        return DefaultEc2MetadataAsyncClient.builder();
+    }
+
+    /**
+     * The builder definition for a {@link Ec2MetadataClient}. All parameters are optional and have default values if not
+     * specified. Therefore, an instance can be simply created with {@code Ec2MetadataAsyncClient.builder().build()} or
+     * {@code Ec2MetadataAsyncClient.create()}, both having the same result.
+     */
+    interface Builder extends Ec2MetadataClientBuilder<Ec2MetadataAsyncClient.Builder, Ec2MetadataAsyncClient> {
+
+        /**
+         * Define the {@link ScheduledExecutorService} used to schedule asynchronous retry attempts. If not specified,
+         * defaults to {@link Executors#newScheduledThreadPool} with a default value of 3 thread in the pool.
+         * If provided, the Ec2MetadataClient will <em>NOT</em> manage the lifetime if the httpClient and must therefore be
+         * closed explicitly by calling the {@link SdkAsyncHttpClient#close()} method on it.
+         *
+         * @param scheduledExecutorService the ScheduledExecutorService to use for retry attempt.
+         * @return a reference to this builder
+         */
+        Builder scheduledExecutorService(ScheduledExecutorService scheduledExecutorService);
+
+        /**
+         * Define the http client used by the Ec2 Metadata client. If provided, the Ec2MetadataClient will <em>NOT</em> manage the
+         * lifetime if the httpClient and must therefore be closed explicitly by calling the {@link SdkAsyncHttpClient#close()}
+         * method on it.
+         *
+         * @param httpClient the http client
+         * @return a reference to this builder
+         */
+        Builder httpClient(SdkAsyncHttpClient httpClient);
+    }
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataClient.java

@@ -0,0 +1,67 @@
+/*
+ * 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.imds;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.http.SdkHttpClient;
+import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
+import software.amazon.awssdk.imds.internal.DefaultEc2MetadataClient;
+import software.amazon.awssdk.utils.SdkAutoCloseable;
+
+
+/**
+ *  Interface to represent the Ec2Metadata Client Class. Used to access instance metadata from a running instance.
+ */
+@SdkPublicApi
+public interface Ec2MetadataClient extends SdkAutoCloseable {
+
+    /**
+     * Gets the specified instance metadata value by the given path.
+     * @param path  Input path
+     * @return Instance metadata value as part of MetadataResponse Object
+     */
+    MetadataResponse get(String path);
+
+    /**
+     * Create an {@link Ec2MetadataClient} instance using the default values.
+     */
+    static Ec2MetadataClient create() {
+        return builder().build();
+    }
+
+    /**
+     * Creates a default builder for {@link Ec2MetadataClient}.
+     */
+    static Builder builder() {
+        return DefaultEc2MetadataClient.builder();
+    }
+
+    /**
+     * The builder definition for a {@link Ec2MetadataClient}.
+     */
+    interface Builder extends Ec2MetadataClientBuilder<Ec2MetadataClient.Builder, Ec2MetadataClient> {
+
+        /**
+         * Define the http client used by the Ec2 Metadata client. If provided, the Ec2MetadataClient will <em>NOT</em> manage the
+         * lifetime if the httpClient and must therefore be closed explicitly by calling the {@link SdkAsyncHttpClient#close()}
+         * method on it.
+         * @param httpClient the http client
+         * @return a reference to this builder
+         */
+        Builder httpClient(SdkHttpClient httpClient);
+    }
+
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataClientBuilder.java

@@ -0,0 +1,70 @@
+/*
+ * 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.imds;
+
+import java.net.URI;
+import java.time.Duration;
+import software.amazon.awssdk.annotations.SdkPublicApi;
+import software.amazon.awssdk.utils.builder.SdkBuilder;
+
+/**
+ * Base shared builder interface for Ec2MetadataClient
+ * @param <B> the Builder Type
+ * @param <T> the Ec2MetadataClient Type
+ */
+@SdkPublicApi
+public interface Ec2MetadataClientBuilder<B, T> extends SdkBuilder<Ec2MetadataClientBuilder<B, T>, T> {
+    /**
+     * Define the retry policy which includes the number of retry attempts for any failed request.
+     *
+     * @param retryPolicy The retry policy which includes the number of retry attempts for any failed request.
+     * @return a reference to this builder
+     */
+    B retryPolicy(Ec2MetadataRetryPolicy retryPolicy);
+
+    Ec2MetadataRetryPolicy getRetryPolicy();
+
+    /**
+     * Define the endpoint of IMDS.
+     *
+     * @param endpoint The endpoint of IMDS.
+     * @return a reference to this builder
+     */
+    B endpoint(URI endpoint);
+
+    URI getEndpoint();
+
+    /**
+     * Define the Time to live (TTL) of the token.
+     *
+     * @param tokenTtl The Time to live (TTL) of the token.
+     * @return a reference to this builder
+     */
+    B tokenTtl(Duration tokenTtl);
+
+    Duration getTokenTtl();
+
+    /**
+     * Define the endpoint mode of IMDS. Supported values include IPv4 and IPv6.
+     *
+     * @param endpointMode The endpoint mode of IMDS. Supported values include IPv4 and IPv6.
+     * @return a reference to this builder
+     */
+    B endpointMode(EndpointMode endpointMode);
+
+    EndpointMode getEndpointMode();
+
+}

core/imds/src/main/java/software/amazon/awssdk/imds/Ec2MetadataRetryPolicy.java

@@ -34,12 +34,14 @@
 @SdkPublicApi
 public class Ec2MetadataRetryPolicy implements ToCopyableBuilder<Ec2MetadataRetryPolicy.Builder, Ec2MetadataRetryPolicy> {
 
+    private static final int DEFAULT_RETRY_ATTEMPTS = 3;
+
     private final BackoffStrategy backoffStrategy;
     private final int numRetries;
 
     private Ec2MetadataRetryPolicy(BuilderImpl builder) {
 
-        this.numRetries = builder.numRetries != null ? builder.numRetries : 3;
+        this.numRetries = builder.numRetries != null ? builder.numRetries : DEFAULT_RETRY_ATTEMPTS;
 
         this.backoffStrategy = builder.backoffStrategy != null ? builder.backoffStrategy :
                                BackoffStrategy.defaultStrategy(RetryMode.STANDARD);

core/imds/src/main/java/software/amazon/awssdk/imds/MetadataResponse.java

@@ -28,7 +28,8 @@
 import software.amazon.awssdk.utils.Validate;
 
 /**
- * The class is used for Response Handling and Parsing the metadata fetched by the get call in the {@link Ec2Metadata} interface.
+ * The class is used for response handling and parsing the metadata fetched by the get call in the {@link Ec2MetadataClient}
+ * interface.
  * The class provides convenience methods to the users to parse the metadata as a String, List and Document.
  */
 @SdkPublicApi