Add examples to show tracking of an upload and a download (#6360)

awsdocs · Apr 24, 2024 · 68d49e9 · 68d49e9
1 parent c3f0adf
commit 68d49e9
Show file tree

Hide file tree

Showing 11 changed files with 271 additions and 58 deletions.
diff --git a/.doc_gen/metadata/s3_metadata.yaml b/.doc_gen/metadata/s3_metadata.yaml
@@ -2997,7 +2997,7 @@ s3_Scenario_UploadStream:
   services:
     s3: {}
 s3_Scenario_MultipartUpload:
-  title: Perform a multipart upload to an &S3; object using an &AWS; SDK
+  title: Perform a multipart upload of an &S3; object using an &AWS; SDK
   title_abbrev: Perform a multipart upload
   synopsis: perform a multipart upload to an &S3; object.
   category: Scenarios
@@ -3172,3 +3172,23 @@ s3_SelectObjectContent:
                 - s3.java2.async.selectObjectContentMethod.main
   services:
     s3: {SelectObjectContent}
+s3_Scenario_TrackUploadDownload:
+  title: Track an &S3; object upload or download using an &AWS; SDK
+  title_abbrev: Track uploads and downloads
+  synopsis: track an &S3; object upload or download.
+  category: Scenarios
+  languages:
+    Java:
+      versions:
+        - sdk_version: 2
+          github: javav2/example_code/s3
+          sdkguide:
+          excerpts:
+            - description: Track the progress of a file upload.
+              snippet_tags:
+                - s3.tm.java2.trackuploadfile.main
+            - description: Track the progress of a file download.
+              snippet_tags:
+                - s3.tm.java2.trackdownloadfile.main
+  services:
+    s3: {PutObject, GetObject}
diff --git a/javav2/example_code/s3/README.md b/javav2/example_code/s3/README.md
@@ -78,6 +78,7 @@ functions within the same service.
 - [Lock Amazon S3 objects](src/main/java/com/example/s3/lockscenario/S3ObjectLockWorkflow.java)
 - [Parse URIs](src/main/java/com/example/s3/ParseUri.java)
 - [Perform a multipart upload](src/main/java/com/example/s3/PerformMultiPartUpload.java)
+- [Track uploads and downloads](src/main/java/com/example/s3/transfermanager/UploadFile.java)
 - [Upload or download large files](src/main/java/com/example/s3/transfermanager/DownloadToDirectory.java)
 - [Upload stream of unknown size](src/main/java/com/example/s3/async/PutObjectFromStreamAsync.java)
 - [Use checksums](src/main/java/com/example/s3/BasicOpsWithChecksums.java)
@@ -155,6 +156,18 @@ This example shows you how to perform a multipart upload to an Amazon S3 object.
 <!--custom.scenarios.s3_Scenario_MultipartUpload.start-->
 <!--custom.scenarios.s3_Scenario_MultipartUpload.end-->
 
+#### Track uploads and downloads
+
+This example shows you how to track an Amazon S3 object upload or download.
+
+
+<!--custom.scenario_prereqs.s3_Scenario_TrackUploadDownload.start-->
+<!--custom.scenario_prereqs.s3_Scenario_TrackUploadDownload.end-->
+
+
+<!--custom.scenarios.s3_Scenario_TrackUploadDownload.start-->
+<!--custom.scenarios.s3_Scenario_TrackUploadDownload.end-->
+
 #### Upload or download large files
 
 This example shows you how to upload or download large files to and from Amazon S3.

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/ParseUri.java b/javav2/example_code/s3/src/main/java/com/example/s3/ParseUri.java
@@ -113,7 +113,7 @@ private static void log(String s3UriElement, Object element) {
         if (element == null) {
             logger.info("{}: {}", s3UriElement, "null");
         } else {
-            logger.info("{}: {}", s3UriElement, element.toString());
+            logger.info("{}: {}", s3UriElement, element);
         }
     }
     // snippet-end:[s3.java2.scenario_uriparsing.main]

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/lockscenario/S3ObjectLockWorkflow.java b/javav2/example_code/s3/src/main/java/com/example/s3/lockscenario/S3ObjectLockWorkflow.java
@@ -31,11 +31,11 @@
  */
 public class S3ObjectLockWorkflow {
 
+    public static final String DASHES = new String(new char[80]).replace("\0", "-");
     static String bucketName;
+    static S3LockActions s3LockActions;
     private static final List<String> bucketNames = new ArrayList<>();
     private static final List<String> fileNames = new ArrayList<>();
-    public static final String DASHES = new String(new char[80]).replace("\0", "-");
-    static S3LockActions s3LockActions;
 
     public static void main(String[] args) {
         // Get the current date and time to ensure bucket name is unique.

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/DownloadFile.java b/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/DownloadFile.java
@@ -4,6 +4,7 @@
 package com.example.s3.transfermanager;
 
 // snippet-start:[s3.tm.java2.downloadfile.import]
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import software.amazon.awssdk.core.sync.RequestBody;
@@ -23,20 +24,21 @@
 // snippet-end:[s3.tm.java2.downloadfile.import]
 
 /**
- * Before running this Java V2 code example, configure your development
- * environment, including your credentials.
- *
- * For more information, see the following documentation topic:
- *
- * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
+ * Before running this example:
+ * <p/>
+ * The SDK must be able to authenticate AWS requests on your behalf. If you have not configured
+ * authentication for SDKs and tools,see https://docs.aws.amazon.com/sdkref/latest/guide/access.html in the AWS SDKs and Tools Reference Guide.
+ * <p/>
+ * You must have a runtime environment configured with the Java SDK.
+ * See https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html in the Developer Guide if this is not set up.
  */
 
 public class DownloadFile {
     private static final Logger logger = LoggerFactory.getLogger(UploadFile.class);
     public final String bucketName = "x-" + UUID.randomUUID();
     public final String key = UUID.randomUUID().toString();
+    private final String downloadedFileName = "downloaded.pdf";
     public String downloadedFileWithPath;
-    private final String downloadedFileName = "downloaded.png";
 
     public DownloadFile() {
         setUp();
@@ -45,18 +47,17 @@ public DownloadFile() {
     public static void main(String[] args) {
         DownloadFile download = new DownloadFile();
         download.downloadFile(S3ClientFactory.transferManager, download.bucketName, download.key,
-            download.downloadedFileWithPath);
+                download.downloadedFileWithPath);
         download.cleanUp();
     }
 
     // snippet-start:[s3.tm.java2.downloadfile.main]
     public Long downloadFile(S3TransferManager transferManager, String bucketName,
                              String key, String downloadedFileWithPath) {
         DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
-            .getObjectRequest(b -> b.bucket(bucketName).key(key))
-            .addTransferListener(LoggingTransferListener.create())
-            .destination(Paths.get(downloadedFileWithPath))
-            .build();
+                .getObjectRequest(b -> b.bucket(bucketName).key(key))
+                .destination(Paths.get(downloadedFileWithPath))
+                .build();
 
         FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);
 
@@ -66,13 +67,56 @@ public Long downloadFile(S3TransferManager transferManager, String bucketName,
     }
     // snippet-end:[s3.tm.java2.downloadfile.main]
 
+    // snippet-start:[s3.tm.java2.trackdownloadfile.main]
+    public void trackDownloadFile(S3TransferManager transferManager, String bucketName,
+                             String key, String downloadedFileWithPath) {
+        DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
+                .getObjectRequest(b -> b.bucket(bucketName).key(key))
+                .addTransferListener(LoggingTransferListener.create())  // Add listener.
+                .destination(Paths.get(downloadedFileWithPath))
+                .build();
+
+        FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);
+
+        CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
+        /*
+            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
+            You can also implement the interface to provide your own logic.
+
+            Configure log4J2 with settings such as the following.
+                <Configuration status="WARN">
+                    <Appenders>
+                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
+                            <PatternLayout pattern="%m%n"/>
+                        </Console>
+                    </Appenders>
+
+                    <Loggers>
+                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
+                            <AppenderRef ref="AlignedConsoleAppender"/>
+                        </logger>
+                    </Loggers>
+                </Configuration>
+
+            Log4J2 logs the progress. The following is example output for a 21.3 MB file download.
+                Transfer initiated...
+                |=======             | 39.4%
+                |===============     | 78.8%
+                |====================| 100.0%
+                Transfer complete!
+        */
+    }
+    // snippet-end:[s3.tm.java2.trackdownloadfile.main]
+
+
     private void setUp() {
         S3ClientFactory.s3Client.createBucket(b -> b.bucket(bucketName));
-        S3ClientFactory.s3Client.putObject(builder -> builder
-            .bucket(bucketName)
-            .key(key), RequestBody.fromString("Hello World"));
-        URL resource = DownloadFile.class.getClassLoader().getResource(".");
         try {
+            S3ClientFactory.s3Client.putObject(builder -> builder
+                    .bucket(bucketName)
+                    .key(key), RequestBody.fromFile(Paths.get(
+                    DownloadFile.class.getClassLoader().getResource("multipartUploadFiles/s3-userguide.pdf").toURI())));
+            URL resource = DownloadFile.class.getClassLoader().getResource(".");
             Path basePath = Paths.get(resource.toURI());
             Path fullPath = basePath.resolve(downloadedFileName);
             downloadedFileWithPath = fullPath.toString();

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/S3ClientFactory.java b/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/S3ClientFactory.java
@@ -21,10 +21,10 @@
  */
 
 public class S3ClientFactory {
-    public static final S3TransferManager transferManager = createCustonTm();
+    public static final S3TransferManager transferManager = createCustomTm();
     public static final S3Client s3Client;
 
-    private static S3TransferManager createCustonTm() {
+    private static S3TransferManager createCustomTm() {
         // snippet-start:[s3.tm.java2.s3clientfactory.create_custom_tm]
         S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
                 .credentialsProvider(DefaultCredentialsProvider.create())

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/UploadFile.java b/javav2/example_code/s3/src/main/java/com/example/s3/transfermanager/UploadFile.java
@@ -19,12 +19,13 @@
 // snippet-end:[s3.tm.java2.uploadfile.import]
 
 /**
- * Before running this Java V2 code example, set up your development
- * environment, including your credentials.
- *
- * For more information, see the following documentation topic:
- *
- * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
+ * Before running this example:
+ * <p/>
+ * The SDK must be able to authenticate AWS requests on your behalf. If you have not configured
+ * authentication for SDKs and tools,see https://docs.aws.amazon.com/sdkref/latest/guide/access.html in the AWS SDKs and Tools Reference Guide.
+ * <p/>
+ * You must have a runtime environment configured with the Java SDK.
+ * See https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html in the Developer Guide if this is not set up.
  */
 
 public class UploadFile {
@@ -40,6 +41,7 @@ public UploadFile() {
     public static void main(String[] args) {
         UploadFile upload = new UploadFile();
         upload.uploadFile(S3ClientFactory.transferManager, upload.bucketName, upload.key, upload.filePathURI);
+        upload.trackUploadFile(S3ClientFactory.transferManager, upload.bucketName, upload.key, upload.filePathURI);
         upload.cleanUp();
     }
 
@@ -48,7 +50,6 @@ public String uploadFile(S3TransferManager transferManager, String bucketName,
                              String key, URI filePathURI) {
         UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
             .putObjectRequest(b -> b.bucket(bucketName).key(key))
-            .addTransferListener(LoggingTransferListener.create())
             .source(Paths.get(filePathURI))
             .build();
 
@@ -59,10 +60,52 @@ public String uploadFile(S3TransferManager transferManager, String bucketName,
     }
     // snippet-end:[s3.tm.java2.uploadfile.main]
 
+    // snippet-start:[s3.tm.java2.trackuploadfile.main]
+    public void trackUploadFile(S3TransferManager transferManager, String bucketName,
+                             String key, URI filePathURI) {
+        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
+                .putObjectRequest(b -> b.bucket(bucketName).key(key))
+                .addTransferListener(LoggingTransferListener.create())  // Add listener.
+                .source(Paths.get(filePathURI))
+                .build();
+
+        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);
+
+        fileUpload.completionFuture().join();
+        /*
+            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
+            You can also implement the interface to provide your own logic.
+
+            Configure log4J2 with settings such as the following.
+                <Configuration status="WARN">
+                    <Appenders>
+                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
+                            <PatternLayout pattern="%m%n"/>
+                        </Console>
+                    </Appenders>
+
+                    <Loggers>
+                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
+                            <AppenderRef ref="AlignedConsoleAppender"/>
+                        </logger>
+                    </Loggers>
+                </Configuration>
+
+            Log4J2 logs the progress. The following is example output for a 21.3 MB file upload.
+                Transfer initiated...
+                |                    | 0.0%
+                |====                | 21.1%
+                |============        | 60.5%
+                |====================| 100.0%
+                Transfer complete!
+        */
+    }
+    // snippet-end:[s3.tm.java2.trackuploadfile.main]
+
     private void setUp() {
         S3ClientFactory.s3Client.createBucket(b -> b.bucket(bucketName));
         // get the file system path to the provided file to upload
-        URL resource = UploadFile.class.getClassLoader().getResource("image.png");
+        URL resource = UploadFile.class.getClassLoader().getResource("multipartUploadFiles/s3-userguide.pdf");
         try {
             filePathURI = resource.toURI();
         } catch (URISyntaxException | NullPointerException e) {

diff --git a/javav2/example_code/s3/src/main/java/com/example/s3/util/MemoryLog4jAppender.java b/javav2/example_code/s3/src/main/java/com/example/s3/util/MemoryLog4jAppender.java
@@ -23,6 +23,7 @@
 public class MemoryLog4jAppender extends AbstractAppender {
 
     private Map<String, String> eventMap = new LinkedHashMap<>();
+    private StringBuilder stringBuilder = new StringBuilder();
 
     protected MemoryLog4jAppender(String name, Filter filter) {
         super(name, filter, null);
@@ -43,9 +44,13 @@ public void append(LogEvent event) {
         } else {
             eventMap.put (eventWithParameters.toString(), null);
         }
+        stringBuilder.append(eventWithParameters.getFormattedMessage() + "\n");
     }
 
     public Map<String, String> getEventMap(){
         return this.eventMap;
     }
+    public String getEventsAsString(){
+        return stringBuilder.toString();
+    }
 }
diff --git a/javav2/example_code/s3/src/main/resources/log4j2.xml b/javav2/example_code/s3/src/main/resources/log4j2.xml
@@ -1,21 +1,30 @@
 <Configuration status="WARN">
     <Appenders>
         <Console name="ConsoleAppender" target="SYSTEM_OUT">
-            <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
+            <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n"/>
         </Console>
         <MemoryLog4jAppender name="MemoryLog4jAppender"/>
+        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
+            <PatternLayout pattern="%m%n"/>
+        </Console>
     </Appenders>
 
     <Loggers>
         <Root level="WARN">
             <AppenderRef ref="ConsoleAppender"/>
-            <AppenderRef ref="MemoryLog4jAppender"/>
         </Root>
-        <Logger name="software.amazon.awssdk" level="WARN" />
-        <Logger name="software.amazon.awssdk.request" level="INFO" />
-        <Logger name="org.apache.http.wire" level="INFO" />
+        <Logger name="software.amazon.awssdk" level="WARN"/>
+        <Logger name="software.amazon.awssdk.request" level="INFO"/>
+        <Logger name="org.apache.http.wire" level="INFO"/>
         <logger name="TransferManagerTest" level="INFO"/>
-        <logger name="S3TestWatcher" level="INFO" />
-        <logger name="com.example.s3" level="INFO" />
+        <logger name="S3TestWatcher" level="INFO"/>
+        <logger name="com.example.s3" level="INFO"/>
+        <logger name="com.example.s3.ParseUri">
+            <AppenderRef ref="MemoryLog4jAppender"/>
+        </logger>
+        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
+            <AppenderRef ref="AlignedConsoleAppender"/>
+            <AppenderRef ref="MemoryLog4jAppender"/>
+        </logger>
     </Loggers>
 </Configuration>