비동기 클라이언트 사용 APIs 비동기 방식으로 스트리밍 처리 고급 비동기 옵션 구성

비동기 프로그래밍 사용

는 몇 스레드에서 높은 동시성을 구현하는 비차단 I/O 지원이 포함된 비동기 클라이언트를 AWS SDK for Java 2.x 특징으로 합니다. 그러나 총 비차단 I/O는 보장되지 않습니다. 비동기 클라이언트는 자격 증명 검색, AWS 서명 버전 4(SigV4)를 사용한 서명 요청 또는 엔드포인트 검색과 같은 경우에 차단 호출을 수행할 수 있습니다.

비동기 메서드는 클라이언트가 서비스로부터 응답을 받을 때까지 스레드의 실행을 차단합니다. 비동기 메서드는 (값을) 즉시 반환하며, 응답을 기다리지 않고 제어 권한을 호출 스레드에 넘겨줍니다.

비동기 메서드는 응답이 제공되기 전에 (값을) 반환하므로 준비되었을 때 응답을 가져올 방법이 필요합니다. 응답이 준비되면 액세스할 수 있는 AWS SDK for Java 반환 CompletableFuture 객체의 2.x에서 비동기 클라이언트를 위한 방법입니다.

비동기 클라이언트 사용 APIs

비동기식 클라이언트 메서드의 서명은 동기식 클라이언트 메서드와 동일하지만 비동기식 메서드는 향후 비동기식 작업의 결과가 포함된 CompletableFuture 객체를 반환합니다. SDK의 비동기 메서드가 실행되는 동안 오류가 발생하면 오류가 로 발생합니다CompletionException.

결과를 얻는 데 사용할 수 있는 한 가지 방법은 whenComplete() 메서드 호출에서 CompletableFuture 반환된 에 SDK 메서드를 연결하는 것입니다. whenComplete() 메서드는 비동기 호출이 완료된 방식에 CompletionException 따라 결과 또는 유형의 스로우 가능 객체를 수신합니다. 호출 코드whenComplete()로 반환되기 전에 결과를 처리하거나 확인하는 작업을 에 제공합니다.

SDK 메서드에서 반환한 객체 이외의 다른 것을 반환하려면 메handle()서드를 대신 사용합니다. handle() 메서드는 와 동일한 파라미터를 사용하지whenComplete()만 결과를 처리하고 객체를 반환할 수 있습니다.

비동기 체인이 완료 결과를 완료하고 검색할 때까지 기다리려면 join() 메서드를 호출할 수 있습니다. 체인에서 Throwable 객체를 처리하지 않은 경우 join() 메서드는 선택하지 않은 를 발생CompletionException시켜 원래 예외를 래핑합니다. 를 사용하여 원래 예외에 액세스합니다CompletionException#getCause(). CompletableFuture#get() 메서드를 호출하여 완료 결과를 얻을 수도 있습니다. 하지만 get() 메서드는 확인된 예외를 발생시킬 수 있습니다.

다음 예제에서는 DynamoDB 비동기 클라이언트의 listTables() 메서드를 사용하는 방법에 대한 두 가지 변형을 보여줍니다. 에 전달된 작업은 whenComplete() 단순히 성공적인 응답을 로깅하는 반면 버전은 테이블 이름 목록을 handle() 추출하고 목록을 반환합니다. 두 경우 모두 비동기 체인에서 오류가 발생하는 경우 클라이언트 코드가 오류를 처리할 수 있도록 오류가 다시 발생됩니다.

가져오기


import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest;
import software.amazon.awssdk.services.dynamodb.model.ListTablesResponse;

import java.util.List;
import java.util.concurrent.CompletableFuture;

코드

whenComplete() variation


public class DynamoDbAsyncListTables {

    public static void main(String[] args) {
        Region region = Region.US_EAST_1;
        DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder().region(region).build();
        try {
            ListTablesResponse listTablesResponse = listTablesWhenComplete(dynamoDbAsyncClient).join();  // The join() method may throw a CompletionException.
            if (listTablesResponse.hasTableNames()){
                System.out.println("Table exist in this region: " + region.id());
            }
        } catch (RuntimeException e) {
            // Handle as needed. Here we simply print out the class names.
            System.out.println(e.getClass()); // Prints 'class java.util.concurrent.CompletionException'.
            System.out.println(e.getCause().getClass()); // Prints 'class software.amazon.awssdk.services.dynamodb.model.DynamoDbException'.
        }
    }

    public static CompletableFuture<ListTablesResponse> listTablesWhenComplete(DynamoDbAsyncClient client) {
        return client.listTables(ListTablesRequest.builder().build())
            .whenComplete((listTablesResponse, throwable) -> {
                if (listTablesResponse != null) {  // Consume the response.
                    System.out.println("The SDK's listTables method completed successfully.");
                } else {
                    RuntimeException cause = (RuntimeException) throwable.getCause(); // If an error was thrown during the SDK's listTables method it is wrapped in a CompletionException.
                                                                                      // The SDK throws only RuntimeExceptions, so this is a safe cast.
                    System.out.println(cause.getMessage());  // Log error here, but rethrow so the calling code can handle as needed.
                    throw cause;
                }
            });
    }

handle() variation


public class DynamoDbAsyncListTables {

    public static void main(String[] args) {
        Region region = Region.US_EAST_1;
        DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder().region(region).build();
        try {
            List<String> tableNames = listTablesHandle(dynamoDbAsyncClient).join(); // The join() method may throw a CompletionException.
            tableNames.forEach(System.out::println);
        } catch (RuntimeException e) {
            // Handle as needed. Here we simply print out the class names.
            System.out.println(e.getClass()); // Prints 'class java.util.concurrent.CompletionException'.
            System.out.println(e.getCause().getClass()); // Prints 'class software.amazon.awssdk.services.dynamodb.model.DynamoDbException'.
        }
    }

    public static CompletableFuture<List<String>> listTablesHandle(DynamoDbAsyncClient client) {
        return client.listTables(ListTablesRequest.builder().build())
            .handle((listTablesResponse, throwable) -> {
                if (listTablesResponse != null) {
                    return listTablesResponse.tableNames(); // Return the list of table names.
                } else {
                    RuntimeException cause = (RuntimeException) throwable.getCause(); // If an error was thrown during the SDK's listTables method it is wrapped in a CompletionException.
                                                                                      // The SDK throws only RuntimeExceptions, so this is a safe cast.
                    System.out.println(cause.getMessage());  // Log error here, but rethrow so the calling code can handle as needed.
                    throw cause;
                }
            });
    }
}

비동기 방식으로 스트리밍 처리

스트리밍 콘텐츠가 있는 비동기식 메서드의 경우 콘텐츠를 점진적으로 제공AsyncRequestBody하려면 를 제공하고 응답을 수신하고 처리AsyncResponseTransformer하려면 를 제공해야 합니다.

다음 예제에서는 PutObject 작업의 Amazon S3 비동기 형식을 사용하여 파일을 비동기식으로 에 업로드합니다.

가져오기


import software.amazon.awssdk.core.async.AsyncRequestBody;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.PutObjectResponse;
import java.nio.file.Paths;
import java.util.concurrent.CompletableFuture;

코드


/**
 * To run this AWS code example, ensure that you have setup your development environment, including your AWS credentials.
 *
 * For information, see this documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 */

public class S3AsyncOps {

     public static void main(String[] args) {

         final String USAGE = "\n" +
                 "Usage:\n" +
                 "    S3AsyncOps <bucketName> <key> <path>\n\n" +
                 "Where:\n" +
                 "    bucketName - the name of the Amazon S3 bucket (for example, bucket1). \n\n" +
                 "    key - the name of the object (for example, book.pdf). \n" +
                 "    path - the local path to the file (for example, C:/AWS/book.pdf). \n" ;

        if (args.length != 3) {
            System.out.println(USAGE);
             System.exit(1);
        }

        String bucketName = args[0];
        String key = args[1];
        String path = args[2];

        Region region = Region.US_WEST_2;
        S3AsyncClient client = S3AsyncClient.builder()
                .region(region)
                .build();

        PutObjectRequest objectRequest = PutObjectRequest.builder()
                .bucket(bucketName)
                .key(key)
                .build();

        // Put the object into the bucket
        CompletableFuture<PutObjectResponse> future = client.putObject(objectRequest,
                AsyncRequestBody.fromFile(Paths.get(path))
        );
        future.whenComplete((resp, err) -> {
            try {
                if (resp != null) {
                    System.out.println("Object uploaded. Details: " + resp);
                } else {
                    // Handle error
                    err.printStackTrace();
                }
            } finally {
                // Only close the client when you are completely done with it
                client.close();
            }
        });

        future.join();
    }
}

다음 예제에서는 비동기식 GetObject 작업을 Amazon S3 사용하여 에서 파일을 가져옵니다.

가져오기


import software.amazon.awssdk.core.async.AsyncResponseTransformer;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.services.s3.model.GetObjectResponse;
import java.nio.file.Paths;
import java.util.concurrent.CompletableFuture;

코드


/**
 * To run this AWS code example, ensure that you have setup your development environment, including your AWS credentials.
 *
 * For information, see this documentation topic:
 *
 * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
 */

public class S3AsyncStreamOps {

    public static void main(String[] args) {

        final String USAGE = "\n" +
                "Usage:\n" +
                "    S3AsyncStreamOps <bucketName> <objectKey> <path>\n\n" +
                "Where:\n" +
                "    bucketName - the name of the Amazon S3 bucket (for example, bucket1). \n\n" +
                "    objectKey - the name of the object (for example, book.pdf). \n" +
                "    path - the local path to the file (for example, C:/AWS/book.pdf). \n" ;

        if (args.length != 3) {
            System.out.println(USAGE);
            System.exit(1);
         }

        String bucketName = args[0];
        String objectKey = args[1];
        String path = args[2];

        Region region = Region.US_WEST_2;
        S3AsyncClient client = S3AsyncClient.builder()
                .region(region)
                .build();

        GetObjectRequest objectRequest = GetObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        CompletableFuture<GetObjectResponse> futureGet = client.getObject(objectRequest,
                AsyncResponseTransformer.toFile(Paths.get(path)));

        futureGet.whenComplete((resp, err) -> {
            try {
                if (resp != null) {
                    System.out.println("Object downloaded. Details: "+resp);
                } else {
                    err.printStackTrace();
                }
            } finally {
               // Only close the client when you are completely done with it
                client.close();
            }
        });
        futureGet.join();
    }
}

고급 비동기 옵션 구성

AWS SDK for Java 2.x는 비동기 이벤트 기반 네트워크 애플리케이션 프레임워크인 Netty 를 사용하여 I/O 스레드를 처리합니다. AWS SDK for Java 2.x는 클라이언트 요청에서 Netty HTTP 클라이언트로 반환되는 선물을 완료하기 위해 Netty ExecutorService 뒤에 를 생성합니다. 이러한 추상화는 개발자가 스레드 중지 또는 대기를 선택하는 경우 애플리케이션이 비동기 프로세스를 차단하는 위험을 줄여줍니다. 기본적으로 각 비동기 클라이언트는 프로세서 수에 따라 스레드 풀을 만들고 ExecutorService 내에서 대기열의 작업을 관리합니다.

비동기 클라이언트를 빌드할 ExecutorService 때 의 특정 JDK 구현을 지정할 수 있습니다. 다음 조각은 고정된 수의 스레드ExecutorService로 를 생성합니다.

코드


S3AsyncClient clientThread = S3AsyncClient.builder()
  .asyncConfiguration(
    b -> b.advancedOption(SdkAdvancedAsyncClientOption
      .FUTURE_COMPLETION_EXECUTOR,
      Executors.newFixedThreadPool(10)
    )
  )
  .build();

성능을 최적화하기 위해 자체 스레드 풀 실행기를 관리하고 클라이언트를 구성할 때 포함할 수 있습니다.


ThreadPoolExecutor executor = new ThreadPoolExecutor(50, 50,
    10, TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(<custom_value>),
    new ThreadFactoryBuilder()
      .threadNamePrefix("sdk-async-response").build());

// Allow idle core threads to time out
executor.allowCoreThreadTimeOut(true);

S3AsyncClient clientThread = S3AsyncClient.builder()
  .asyncConfiguration(
    b -> b.advancedOption(SdkAdvancedAsyncClientOption
      .FUTURE_COMPLETION_EXECUTOR,
      executor
    )
  )
  .build();

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

리소스 상태 설문 조사

HTTP/2 작업