|
| 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.imds; |
| 17 | + |
| 18 | +import java.util.concurrent.CompletableFuture; |
| 19 | +import java.util.concurrent.Executors; |
| 20 | +import java.util.concurrent.ScheduledExecutorService; |
| 21 | +import software.amazon.awssdk.annotations.SdkPublicApi; |
| 22 | +import software.amazon.awssdk.core.exception.SdkClientException; |
| 23 | +import software.amazon.awssdk.http.async.SdkAsyncHttpClient; |
| 24 | +import software.amazon.awssdk.imds.internal.DefaultEc2MetadataAsyncClient; |
| 25 | +import software.amazon.awssdk.utils.SdkAutoCloseable; |
| 26 | + |
| 27 | +/** |
| 28 | + * Interface to represent the Ec2Metadata Client Class. Used to access instance metadata from a running EC2 instance. |
| 29 | + * <h2>Instantiate the Ec2MetadataAsyncClient</h2> |
| 30 | + * <h3>Default configuration</h3> |
| 31 | + * {@snippet : |
| 32 | + * Ec2MetadataAsyncClient client = Ec2MetadataAsyncClient.create(); |
| 33 | + * } |
| 34 | + * <h3>Custom configuration</h3> |
| 35 | + * Example of a client configured for using IPV6 and a fixed delay for retry attempts : |
| 36 | + * {@snippet : |
| 37 | + * Ec2MetadataAsyncClient client = Ec2MetadataAsyncClient.builder() |
| 38 | + * .retryPolicy(p -> p.backoffStrategy(FixedDelayBackoffStrategy.create(Duration.ofMillis(500)))) |
| 39 | + * .endpointMode(EndpointMode.IPV6) |
| 40 | + * .build(); |
| 41 | + * } |
| 42 | + * <h2>Use the client</h2> |
| 43 | + * Call the {@code get} method on the client with a path to an instance metadata: |
| 44 | + * {@snippet : |
| 45 | + * Ec2MetadataAsyncClient client = Ec2MetadataAsyncClient.create(); |
| 46 | + * CompletableFuture<Ec2MetadataResponse> response = client.get("/latest/meta-data/"); |
| 47 | + * response.thenAccept(System.out::println); |
| 48 | + * } |
| 49 | + * <h2>Closing the client</h2> |
| 50 | + * Once all operations are done, you may close the client to free any resources used by it. |
| 51 | + * {@snippet : |
| 52 | + * Ec2MetadataAsyncClient client = Ec2MetadataAsyncClient.create(); |
| 53 | + * // ... do the things |
| 54 | + * client.close(); |
| 55 | + * } |
| 56 | + * <br/>Note: A single client instance should be reused for multiple requests when possible. |
| 57 | + */ |
| 58 | +@SdkPublicApi |
| 59 | +public interface Ec2MetadataAsyncClient extends SdkAutoCloseable { |
| 60 | + |
| 61 | + /** |
| 62 | + * Gets the specified instance metadata value by the given path. For more information about instance metadata, check the |
| 63 | + * <a href=https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html>Instance metadata documentation</a>. |
| 64 | + * |
| 65 | + * @param path Input path |
| 66 | + * @return A CompletableFuture that completes when the MetadataResponse is made available. |
| 67 | + */ |
| 68 | + CompletableFuture<Ec2MetadataResponse> get(String path); |
| 69 | + |
| 70 | + /** |
| 71 | + * Create an {@link Ec2MetadataAsyncClient} instance using the default values. |
| 72 | + * |
| 73 | + * @return the client instance. |
| 74 | + */ |
| 75 | + static Ec2MetadataAsyncClient create() { |
| 76 | + return builder().build(); |
| 77 | + } |
| 78 | + |
| 79 | + /** |
| 80 | + * Creates a builder for an async client instance. |
| 81 | + * @return the newly created builder instance. |
| 82 | + */ |
| 83 | + static Ec2MetadataAsyncClient.Builder builder() { |
| 84 | + return DefaultEc2MetadataAsyncClient.builder(); |
| 85 | + } |
| 86 | + |
| 87 | + /** |
| 88 | + * The builder definition for a {@link Ec2MetadataClient}. All parameters are optional and have default values if not |
| 89 | + * specified. Therefore, an instance can be simply created with {@code Ec2MetadataAsyncClient.builder().build()} or |
| 90 | + * {@code Ec2MetadataAsyncClient.create()}, both having the same result. |
| 91 | + */ |
| 92 | + interface Builder extends Ec2MetadataClientBuilder<Ec2MetadataAsyncClient.Builder, Ec2MetadataAsyncClient> { |
| 93 | + |
| 94 | + /** |
| 95 | + * Define the {@link ScheduledExecutorService} used to schedule asynchronous retry attempts. If provided, the |
| 96 | + * Ec2MetadataClient will <em>NOT</em> manage the lifetime if the httpClient and must therefore be |
| 97 | + * closed explicitly by calling the {@link SdkAsyncHttpClient#close()} method on it. |
| 98 | + * <p> |
| 99 | + * If not specified, defaults to {@link Executors#newScheduledThreadPool} with a default value of 3 thread in the |
| 100 | + * pool. |
| 101 | + * |
| 102 | + * @param scheduledExecutorService the ScheduledExecutorService to use for retry attempt. |
| 103 | + * @return a reference to this builder |
| 104 | + */ |
| 105 | + Builder scheduledExecutorService(ScheduledExecutorService scheduledExecutorService); |
| 106 | + |
| 107 | + /** |
| 108 | + * Define the http client used by the Ec2 Metadata client. If provided, the Ec2MetadataClient will <em>NOT</em> manage the |
| 109 | + * lifetime if the httpClient and must therefore be closed explicitly by calling the {@link SdkAsyncHttpClient#close()} |
| 110 | + * method on it. |
| 111 | + * <p> |
| 112 | + * If not specified, the IMDS client will look for a SdkAsyncHttpClient class included in the classpath of the |
| 113 | + * application and creates a new instance of that class, managed by the IMDS Client, that will be closed when the IMDS |
| 114 | + * Client is closed. If no such class can be found, will throw a {@link SdkClientException}. |
| 115 | + * |
| 116 | + * @param httpClient the http client |
| 117 | + * @return a reference to this builder |
| 118 | + */ |
| 119 | + Builder httpClient(SdkAsyncHttpClient httpClient); |
| 120 | + |
| 121 | + /** |
| 122 | + * An http client builder used to retrieve an instance of an {@link SdkAsyncHttpClient}. If specified, the Ec2 |
| 123 | + * Metadata Client will use the instance returned by the builder and manage its lifetime by closing the http client |
| 124 | + * once the Ec2 Client itself is closed. |
| 125 | + * |
| 126 | + * @param builder the builder to used to retrieve an instance. |
| 127 | + * @return a reference to this builder |
| 128 | + */ |
| 129 | + Builder httpClient(SdkAsyncHttpClient.Builder<?> builder); |
| 130 | + } |
| 131 | +} |
0 commit comments