Improve error message for ResponseTransformer.toFile() and AsyncRespo… (#6918)

* Improve error message for ResponseTransformer.toFile() and AsyncResponseTransformer.toFile() when parent directory is missing

# Conflicts:
#	.changes/next-release/bugfix-AWSSDKforJavav2-1f2b503.json

* Update error message

Author: zoewangg

.changes/next-release/bugfix-AWSSDKforJavav2-8da4e26.json

@@ -0,0 +1,6 @@
+{
+    "type": "bugfix",
+    "category": "AWS SDK for Java v2",
+    "contributor": "",
+    "description": "Improved error message when `ResponseTransformer.toFile()` or `AsyncResponseTransformer.toFile()` fails because the parent directory does not exist. The error now indicates that the parent directory must be created before calling the method."
+}

core/sdk-core/src/main/java/software/amazon/awssdk/core/FileTransformerConfiguration.java

@@ -105,6 +105,7 @@ public static Builder builder() {
      * <p>
      * Always create a new file. If the file already exists, {@link FileAlreadyExistsException} will be thrown.
      * In the event of an error, the SDK will attempt to delete the file (whatever has been written to it so far).
+     * The file's parent directories must already exist; the SDK will not auto-create them.
      */
     public static FileTransformerConfiguration defaultCreateNew() {
         return builder().fileWriteOption(FileWriteOption.CREATE_NEW)
@@ -116,7 +117,8 @@ public static FileTransformerConfiguration defaultCreateNew() {
      * Returns the default {@link FileTransformerConfiguration} for {@link FileWriteOption#CREATE_OR_REPLACE_EXISTING}
      * <p>
      * Create a new file if it doesn't exist, otherwise replace the existing file.
-     * In the event of an error, the SDK will NOT attempt to delete the file, leaving it as-is
+     * In the event of an error, the SDK will NOT attempt to delete the file, leaving it as-is.
+     * The file's parent directories must already exist; the SDK will not auto-create them.
      */
     public static FileTransformerConfiguration defaultCreateOrReplaceExisting() {
         return builder().fileWriteOption(FileWriteOption.CREATE_OR_REPLACE_EXISTING)
@@ -128,7 +130,8 @@ public static FileTransformerConfiguration defaultCreateOrReplaceExisting() {
      * Returns the default {@link FileTransformerConfiguration} for {@link FileWriteOption#CREATE_OR_APPEND_TO_EXISTING}
      * <p>
      * Create a new file if it doesn't exist, otherwise append to the existing file.
-     * In the event of an error, the SDK will NOT attempt to delete the file, leaving it as-is
+     * In the event of an error, the SDK will NOT attempt to delete the file, leaving it as-is.
+     * The file's parent directories must already exist; the SDK will not auto-create them.
      */
     public static FileTransformerConfiguration defaultCreateOrAppend() {
         return builder().fileWriteOption(FileWriteOption.CREATE_OR_APPEND_TO_EXISTING)
@@ -179,16 +182,19 @@ public int hashCode() {
     public enum FileWriteOption {
         /**
          * Always create a new file. If the file already exists, {@link FileAlreadyExistsException} will be thrown.
+         * The file's parent directories must already exist; the SDK will not auto-create them.
          */
         CREATE_NEW,
 
         /**
          * Create a new file if it doesn't exist, otherwise replace the existing file.
+         * The file's parent directories must already exist; the SDK will not auto-create them.
          */
         CREATE_OR_REPLACE_EXISTING,
 
         /**
          * Create a new file if it doesn't exist, otherwise append to the existing file.
+         * The file's parent directories must already exist; the SDK will not auto-create them.
          */
         CREATE_OR_APPEND_TO_EXISTING,
 

core/sdk-core/src/main/java/software/amazon/awssdk/core/async/AsyncResponseTransformer.java

@@ -177,6 +177,9 @@ default String name() {
      * SDK will attempt to delete the file (whatever has been written to it so far). If the file already exists, an exception will
      * be thrown.
      *
+     * <p>The file's parent directories must already exist. The SDK will not auto-create directories, and a
+     * {@link java.nio.file.NoSuchFileException} will be thrown if they are missing.
+     *
      * @param path        Path to file to write to.
      * @param <ResponseT> Pojo Response type.
      * @return AsyncResponseTransformer instance.
@@ -190,6 +193,9 @@ static <ResponseT> AsyncResponseTransformer<ResponseT, ResponseT> toFile(Path pa
      * Creates an {@link AsyncResponseTransformer} that writes all the content to the given file with the specified
      * {@link FileTransformerConfiguration}.
      *
+     * <p>The file's parent directories must already exist. The SDK will not auto-create directories, and a
+     * {@link java.nio.file.NoSuchFileException} will be thrown if they are missing.
+     *
      * @param path        Path to file to write to.
      * @param config      configuration for the transformer
      * @param <ResponseT> Pojo Response type.
@@ -217,6 +223,9 @@ static <ResponseT> AsyncResponseTransformer<ResponseT, ResponseT> toFile(
      * SDK will attempt to delete the file (whatever has been written to it so far). If the file already exists, an exception will
      * be thrown.
      *
+     * <p>The file's parent directories must already exist. The SDK will not auto-create directories, and a
+     * {@link java.nio.file.NoSuchFileException} will be thrown if they are missing.
+     *
      * @param file        File to write to.
      * @param <ResponseT> Pojo Response type.
      * @return AsyncResponseTransformer instance.

core/sdk-core/src/main/java/software/amazon/awssdk/core/internal/async/FileAsyncResponseTransformer.java

@@ -126,7 +126,15 @@ private AsynchronousFileChannel createChannel(Path path) throws IOException {
         }
 
         ExecutorService executorService = configuration.executorService().orElse(null);
-        return AsynchronousFileChannel.open(path, options, executorService);
+        try {
+            return AsynchronousFileChannel.open(path, options, executorService);
+        } catch (NoSuchFileException e) {
+            if (configuration.fileWriteOption() == WRITE_TO_POSITION) {
+                throw e;
+            }
+            throw new NoSuchFileException(e.getFile(), e.getOtherFile(),
+                                          "Verify that the file's parent directories exist. The SDK will not auto-create them.");
+        }
     }
 
     @Override

core/sdk-core/src/main/java/software/amazon/awssdk/core/sync/ResponseTransformer.java

@@ -109,7 +109,10 @@ default String name() {
 
     /**
      * Creates a response transformer that writes all response content to the specified file. If the file already exists
-     * then a {@link java.nio.file.FileAlreadyExistsException} will be thrown.
+     * then a {@link FileAlreadyExistsException} will be thrown.
+     *
+     * <p>The file's parent directories must already exist. The SDK will not auto-create directories, and a
+     * {@link NoSuchFileException} will be thrown if they are missing.
      *
      * @param path        Path to file to write to.
      * @param <ResponseT> Type of unmarshalled response POJO.
@@ -124,7 +127,7 @@ public ResponseT transform(ResponseT response, AbortableInputStream inputStream)
                     Files.copy(inputStream, path);
                     return response;
                 } catch (IOException copyException) {
-                    String copyError = "Failed to read response into file: " + path;
+                    String copyError = copyErrorMessage(path, copyException);
 
                     if (shouldThrowIOException(copyException)) {
                         throw new IOException(copyError, copyException);
@@ -167,9 +170,21 @@ static boolean shouldThrowIOException(IOException copyException) {
                copyException instanceof AccessDeniedException;
     }
 
+    static String copyErrorMessage(Path path, IOException copyException) {
+        String baseMessage = "Failed to read response into file: " + path;
+        if (copyException instanceof NoSuchFileException) {
+            return baseMessage + ". Verify that the file's parent directories exist."
+                   + " The SDK will not auto-create them.";
+        }
+        return baseMessage;
+    }
+
     /**
      * Creates a response transformer that writes all response content to the specified file. If the file already exists
-     * then a {@link java.nio.file.FileAlreadyExistsException} will be thrown.
+     * then a {@link FileAlreadyExistsException} will be thrown.
+     *
+     * <p>The file's parent directories must already exist. The SDK will not auto-create directories, and a
+     * {@link NoSuchFileException} will be thrown if they are missing.
      *
      * @param file        File to write to.
      * @param <ResponseT> Type of unmarshalled response POJO.

core/sdk-core/src/test/java/software/amazon/awssdk/core/internal/async/FileAsyncResponseTransformerTest.java

@@ -318,6 +318,49 @@ void onStreamFailed_shouldCompleteFutureExceptionally() {
         assertThat(future).isCompletedExceptionally();
     }
 
+    private static List<FileTransformerConfiguration> parentDirConfigurations() {
+        return java.util.Arrays.asList(
+            FileTransformerConfiguration.defaultCreateNew(),
+            FileTransformerConfiguration.defaultCreateOrReplaceExisting(),
+            FileTransformerConfiguration.defaultCreateOrAppend()
+        );
+    }
+
+    @ParameterizedTest
+    @MethodSource("parentDirConfigurations")
+    void parentDirectoryDoesNotExist_throwsWithHelpfulMessage(FileTransformerConfiguration config) {
+        Path testPath = testFs.getPath("nonexistent-parent", "test_file.txt");
+        FileAsyncResponseTransformer<String> transformer = new FileAsyncResponseTransformer<>(testPath, config);
+
+        CompletableFuture<String> future = transformer.prepare();
+        transformer.onResponse("foobar");
+        transformer.onStream(testPublisher("content"));
+
+        assertThat(future).failsWithin(1, TimeUnit.SECONDS)
+                          .withThrowableOfType(ExecutionException.class)
+                          .withCauseInstanceOf(NoSuchFileException.class)
+                          .withMessageContaining("Verify that the file's parent directories exist")
+                          .withMessageContaining("The SDK will not auto-create them");
+    }
+
+    @Test
+    void writeToPosition_fileDoesNotExist_throwsWithHelpfulMessage() {
+        Path testPath = testFs.getPath("nonexistent_file.txt");
+        FileAsyncResponseTransformer<String> transformer = new FileAsyncResponseTransformer<>(testPath,
+            FileTransformerConfiguration.builder()
+                                        .failureBehavior(DELETE)
+                                        .fileWriteOption(FileWriteOption.WRITE_TO_POSITION)
+                                        .build());
+
+        CompletableFuture<String> future = transformer.prepare();
+        transformer.onResponse("foobar");
+        transformer.onStream(testPublisher("content"));
+
+        assertThat(future).failsWithin(1, TimeUnit.SECONDS)
+                          .withThrowableOfType(ExecutionException.class)
+                          .withCauseInstanceOf(NoSuchFileException.class);
+    }
+
     private static void stubSuccessfulStreaming(String newContent, FileAsyncResponseTransformer<String> transformer) throws Exception {
         CompletableFuture<String> future = transformer.prepare();
         transformer.onResponse("foobar");

core/sdk-core/src/test/java/software/amazon/awssdk/core/sync/ResponseTransformerToFileTest.java

@@ -0,0 +1,50 @@
+/*
+ * 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.core.sync;
+
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.NoSuchFileException;
+import java.nio.file.Path;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import software.amazon.awssdk.http.AbortableInputStream;
+
+
+class ResponseTransformerToFileTest {
+
+    @TempDir
+    Path tempDir;
+
+    @Test
+    void toFile_parentDirectoryDoesNotExist_throwsWithHelpfulMessage() throws Exception {
+        Path fileWithMissingParent = tempDir.resolve("nonexistent-parent/subdir/output.wav");
+        ResponseTransformer<String, String> transformer = ResponseTransformer.toFile(fileWithMissingParent);
+
+        AbortableInputStream inputStream = AbortableInputStream.create(
+            new ByteArrayInputStream("test-content".getBytes(StandardCharsets.UTF_8))
+        );
+
+        assertThatThrownBy(() -> transformer.transform("response", inputStream))
+            .isInstanceOf(IOException.class)
+            .hasMessageContaining("Verify that the file's parent directories exist")
+            .hasMessageContaining("The SDK will not auto-create them")
+            .hasCauseInstanceOf(NoSuchFileException.class);
+    }
+}