View a markdown version of this page

Migrate pre-signed URL downloads from AWS SDK for Java v1 to v2 - AWS SDK for Java 2.x
High-level changesChanges in dependencies, packages, and class namesAPI changesConfiguration changes

Migrate pre-signed URL downloads from AWS SDK for Java v1 to v2

Migrate your pre-signed URL download code to use asynchronous processing and access expanded download options in version 2. This topic shows how to migrate from version 1.x (v1) to version 2.x (v2) of the AWS SDK for Java. For information about v2 pre-signed URL download capabilities, see Work with Amazon S3 pre-signed URLs.

High-level changes

The following list summarizes the key differences between v1 and v2 for pre-signed URL downloads:

  • Package: com.amazonaws.services.s3 → software.amazon.awssdk.services.s3.

  • Client class: AmazonS3 (synchronous) → S3AsyncClient (asynchronous).

  • Architecture: Synchronous blocking calls → Asynchronous calls with CompletableFuture.

  • Multipart: Available only through Transfer Manager → Available directly on client with multipartEnabled(true).

  • Transfer Manager: File destination only → File, bytes, or custom transformer.

Changes in dependencies, packages, and class names

The following table shows the dependency and class name changes from v1 to v2.

Change v1 v2

Maven dependencies

 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.amazonaws</groupId>
            <artifactId>aws-java-sdk-bom</artifactId>
            <version>1.12.7971</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-java-sdk-s3</artifactId>
    </dependency>
</dependencies>
 
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.x.x2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
    </dependency>
    <!-- Optional: for Transfer Manager -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3-transfer-manager</artifactId>
    </dependency>
</dependencies>
Package name com.amazonaws.services.s3 software.amazon.awssdk.services.s3
Class names AmazonS3, TransferManager S3AsyncClient, S3TransferManager

1 Latest version on the Maven Central website. 2 Latest version on the Maven Central website.

API changes

S3 client downloads

The following table compares v1 and v2 API calls for S3 client downloads.

Use case v1 v2
Create the client 
AmazonS3 s3Client = 
        AmazonS3ClientBuilder.defaultClient();
 
S3AsyncClient s3AsyncClient = 
        S3AsyncClient.create();
AsyncPresignedUrlExtension extension = 
        s3AsyncClient.presignedUrlExtension();
Generate a pre-signed URL 
Date expiration = new Date(
        System.currentTimeMillis() + 600_000);
URL presignedUrl = s3Client.generatePresignedUrl(
        new GeneratePresignedUrlRequest(
            "my-bucket", "my-key")
            .withMethod(HttpMethod.GET)
            .withExpiration(expiration));
 
S3Presigner presigner = S3Presigner.create();
PresignedGetObjectRequest presigned = 
        presigner.presignGetObject(r -> r
            .getObjectRequest(req -> req
                .bucket("my-bucket").key("my-key"))
            .signatureDuration(Duration.ofMinutes(10)));
URL presignedUrl = presigned.url();
presigner.close();
Create the download request 
PresignedUrlDownloadRequest downloadRequest = 
        new PresignedUrlDownloadRequest(presignedUrl);
 
PresignedUrlDownloadRequest downloadRequest = 
        PresignedUrlDownloadRequest.builder()
            .presignedUrl(presignedUrl)
            .build();
Download to stream 
PresignedUrlDownloadResult result = 
        s3Client.download(downloadRequest);
InputStream content = result.getS3Object()
        .getObjectContent();
 
ResponseBytes<GetObjectResponse> bytes = 
        extension.getObject(downloadRequest,
            AsyncResponseTransformer.toBytes())
        .join();
Download to file 
s3Client.download(downloadRequest,
        new File("/tmp/file.bin"));
 
extension.getObject(downloadRequest,
            Paths.get("/tmp/file.bin"))
        .join();
Download with range 
PresignedUrlDownloadRequest rangeRequest = 
        new PresignedUrlDownloadRequest(presignedUrl);
rangeRequest.setRange(0, 1023);
s3Client.download(rangeRequest);
 
PresignedUrlDownloadRequest rangeRequest = 
        PresignedUrlDownloadRequest.builder()
            .presignedUrl(presignedUrl)
            .range("bytes=0-1023")
            .build();
extension.getObject(rangeRequest,
            Paths.get("/tmp/partial.bin"))
        .join();

Transfer Manager downloads

The following table compares v1 and v2 API calls for Transfer Manager downloads.

Use case v1 v2
Create the Transfer Manager 
TransferManager tm = 
        TransferManagerBuilder.standard().build();
 
S3TransferManager tm = 
        S3TransferManager.create();
Download 
PresignedUrlDownload download = tm.download(
        new PresignedUrlDownloadRequest(presignedUrl),
        new File("/tmp/file.bin"));
download.waitForCompletion();
 
PresignedFileDownload download = 
        tm.downloadFileWithPresignedUrl(
            PresignedDownloadFileRequest.builder()
                .presignedUrlDownloadRequest(
                    downloadRequest)
                .destination(Paths.get("/tmp/file.bin"))
                .addTransferListener(
                    LoggingTransferListener.create())
                .build());
download.completionFuture().join();

For more information, see Download using a pre-signed URL.

Configuration changes

S3 client

The following table describes the S3 client configuration changes from v1 to v2.

Setting v1 v2
Multipart configuration PresignedUrlDownloadConfig.withDownloadSizePerRequest(long) S3AsyncClient.builder().multipartConfiguration(c -> c.minimumPartSizeInBytes(...))
Custom headers PresignedUrlDownloadRequest.putCustomRequestHeader(String, String) Not supported. Only Range and If-Match can be set at download time.

Transfer Manager

The following table describes the Transfer Manager configuration changes from v1 to v2.

Setting v1 v2
Progress tracking PresignedUrlDownloadConfig.withS3progressListener(...) PresignedDownloadFileRequest.builder().addTransferListener(...)
Resume on retry PresignedUrlDownloadConfig.withResumeOnRetry(true) Not supported
Pause/Resume Not supported Not supported
Note

The AWS CRT-based S3 client (S3AsyncClient.crtBuilder()) does not currently support the pre-signed URL extension. Use S3AsyncClient.builder().