fix: raise the released exception classes for local file failures

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: hive-bot

CHANGELOG.md

@@ -193,10 +193,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `translateText()` sends the language codes with the language part
   lower-cased and the rest as given, like document translation, for example
   `zh-Hans`; before, the part after the first `-` was upper-cased.
-- `translateDocument(File, File, ...)` throws a `DocumentTranslationException`
-  instead of an `IOException` when the output file exists or a file cannot be
-  opened, and an `IllegalArgumentException` before any request when the input
-  file does not exist.
 - Text translation accepts a glossary (`setGlossary()`) or glossary list
   (`setGlossaryIds()`) without a source language; the API detects the source
   language and uses the glossary's dictionary for the detected language pair.
@@ -279,13 +275,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`Character.isWhitespace()`) like spoken terms, checks target terms set
   through `replaceAll()` or `Map.Entry.setValue()`, and names an invalid
   character in hexadecimal (`U+001F`).
-- `importTranslationMemoryFromFilepath()` and
-  `exportTranslationMemoryToFilepath()` now throw `DeepLException`, with the
-  original exception as cause, for local I/O failures such as an unreadable
-  input file or a failed write, instead of a raw `IOException`.
-- `exportTranslationMemoryToFilepath()` with a `File` now checks that the output
-  path is free and its directory exists before creating the export job, and
-  throws `DeepLException` otherwise.
+- `exportTranslationMemoryToFilepath()` with a `File` now checks the output
+  path before it creates the export job: an existing file throws `IOException`
+  and a missing directory `FileNotFoundException`, the same classes as before.
 - `waitUntilTranslationMemoryJobDone()` with a timeout, and the import and
   export helpers that use it, now cut the last poll wait short at the timeout
   instead of overrunning it by up to 5 seconds.

README.md

@@ -341,25 +341,29 @@ class Example {  // Continuing class Example from above
         try {
             client.translateDocument(inputFile, outputFile, "en", "de");
         } catch (DocumentTranslationException exception) {
-            // If an error occurs during document translation after the document was
-            // already uploaded, a DocumentTranslationException is thrown. The
-            // document_handle property contains the document handle that may be used to
-            // later retrieve the document from the server, or contact DeepL support.
+            // If an error occurs during document translation, a
+            // DocumentTranslationException is thrown. If the document was already
+            // uploaded, getHandle() returns the document handle that may be used to
+            // later retrieve the document from the server, or contact DeepL support;
+            // otherwise it returns null.
             DocumentHandle handle = exception.getHandle();
-            System.out.printf(
-                    "Error after uploading %s, document handle: id: %s key: %s",
-                    exception.getMessage(),
-                    handle.getDocumentId(),
-                    handle.getDocumentKey());
+            System.out.printf("Error during document translation: %s%n", exception.getMessage());
+            if (handle != null) {
+                System.out.printf(
+                        "Document handle: id: %s key: %s%n",
+                        handle.getDocumentId(),
+                        handle.getDocumentKey());
+            }
         }
     }
 }
 ```
 
-If the input file does not exist, `translateDocument()` throws an
-`IllegalArgumentException` before sending any request. Every other failure,
-including an existing output file or a file that cannot be opened, is thrown as
-a `DocumentTranslationException`; `getHttpStatusCode()` and `getShouldRetry()`
+If a file already exists at the output path, `translateDocument()` throws an
+`IOException` and leaves that file unchanged. A missing or unreadable input file,
+or an output file that cannot be created, throws a `FileNotFoundException`. No
+request is sent in these cases. Later failures are thrown as a
+`DocumentTranslationException`; `getHttpStatusCode()` and `getShouldRetry()`
 report those of the underlying `DeepLException`, if any.
 
 `translateDocument()` is a convenience function that wraps multiple API calls:
@@ -1330,9 +1334,8 @@ The optional timeout is the maximum time to wait for the import to finish; omit
 it to wait indefinitely. The job status is polled every 5 seconds, and the last
 wait is cut short at the timeout.
 
-A missing input file throws `IllegalArgumentException` before any request is
-sent. Any other local I/O failure, such as an unreadable file, throws
-`DeepLException` with the I/O error as its cause.
+A missing input file throws `IllegalArgumentException` and an unreadable file
+throws `IOException`, both before any request is sent.
 
 `ImportTranslationMemoryOptions` groups the import options: `setDisplayName()`,
 `setContentType()` (declared when the job is created and sent with the upload;
@@ -1415,9 +1418,9 @@ class Example {  // Continuing class Example from above
 ```
 
 As with import, the timeout is optional; omit it to wait indefinitely. The output
-path is checked before the export job is created: if a file already exists there
-or its directory does not exist, `DeepLException` is thrown. A failure while
-writing the file also throws `DeepLException`, with the I/O error as its cause.
+path is checked before the export job is created: if a file already exists there,
+`IOException` is thrown, and if its directory does not exist,
+`FileNotFoundException`. A failure while writing the file throws `IOException`.
 Instead of a `File`, you can pass an `OutputStream`, which is not closed:
 
 ```java

deepl-java/src/main/java/com/deepl/api/DeepLClient.java

@@ -2606,11 +2606,10 @@ public void downloadTranslationMemoryExport(TranslationMemoryJob job, OutputStre
    * @return {@link TranslationMemoryJob} object for the completed import; its result carries the ID
    *     of the new translation memory.
    * @throws IllegalArgumentException If the input file does not exist.
-   * @throws IOException Not thrown; local I/O failures are reported as {@link DeepLException}.
-   *     Declared for source compatibility.
+   * @throws IOException If the input file cannot be read.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
-   * @throws DeepLException If the input file cannot be read (with the I/O error as cause), the
-   *     import fails, or any error occurs while communicating with the DeepL API.
+   * @throws DeepLException If the import fails, or any error occurs while communicating with the
+   *     DeepL API.
    */
   public TranslationMemoryJob importTranslationMemoryFromFilepath(
       File inputFile, @Nullable String displayName)
@@ -2631,12 +2630,10 @@ public TranslationMemoryJob importTranslationMemoryFromFilepath(
    * @return {@link TranslationMemoryJob} object for the completed import; its result carries the ID
    *     of the new translation memory.
    * @throws IllegalArgumentException If the input file does not exist.
-   * @throws IOException Not thrown; local I/O failures are reported as {@link DeepLException}.
-   *     Declared for source compatibility.
+   * @throws IOException If the input file cannot be read.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
-   * @throws DeepLException If the input file cannot be read (with the I/O error as cause), the
-   *     timeout is exceeded, the import fails, or any error occurs while communicating with the
-   *     DeepL API.
+   * @throws DeepLException If the timeout is exceeded, the import fails, or any error occurs while
+   *     communicating with the DeepL API.
    * @see DeepLClient#importTranslationMemoryFromFilepath(File, String)
    */
   public TranslationMemoryJob importTranslationMemoryFromFilepath(
@@ -2659,12 +2656,10 @@ public TranslationMemoryJob importTranslationMemoryFromFilepath(
    * @return {@link TranslationMemoryJob} object for the completed import; its result carries the ID
    *     of the new translation memory.
    * @throws IllegalArgumentException If the input file does not exist.
-   * @throws IOException Not thrown; local I/O failures are reported as {@link DeepLException}.
-   *     Declared for source compatibility.
+   * @throws IOException If the input file cannot be read.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
-   * @throws DeepLException If the input file cannot be read (with the I/O error as cause), the
-   *     timeout is exceeded, the import fails, or any error occurs while communicating with the
-   *     DeepL API.
+   * @throws DeepLException If the timeout is exceeded, the import fails, or any error occurs while
+   *     communicating with the DeepL API.
    */
   public TranslationMemoryJob importTranslationMemoryFromFilepath(
       File inputFile, @Nullable ImportTranslationMemoryOptions options)
@@ -2737,12 +2732,11 @@ public TranslationMemoryJob importTranslationMemoryFromFilepath(File inputFile)
    * @param translationMemoryId ID of the translation memory to export.
    * @param outputFile File to write the exported translation memory to.
    * @return {@link TranslationMemoryJob} object for the completed export.
-   * @throws IOException Not thrown; local I/O failures are reported as {@link DeepLException}.
-   *     Declared for source compatibility.
+   * @throws IOException If the output path is occupied or its directory does not exist (checked
+   *     before the export job is created), or writing the file fails.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
-   * @throws DeepLException If the output path is occupied or its directory does not exist (checked
-   *     before the export job is created), writing the file fails (with the I/O error as cause),
-   *     the export fails, or any error occurs while communicating with the DeepL API.
+   * @throws DeepLException If the export fails, or any error occurs while communicating with the
+   *     DeepL API.
    */
   public TranslationMemoryJob exportTranslationMemoryToFilepath(
       String translationMemoryId, File outputFile)
@@ -2760,13 +2754,11 @@ public TranslationMemoryJob exportTranslationMemoryToFilepath(
    *     indefinitely. The job status is polled every 5 seconds; the last wait is cut short at the
    *     timeout.
    * @return {@link TranslationMemoryJob} object for the completed export.
-   * @throws IOException Not thrown; local I/O failures are reported as {@link DeepLException}.
-   *     Declared for source compatibility.
+   * @throws IOException If the output path is occupied or its directory does not exist (checked
+   *     before the export job is created), or writing the file fails.
    * @throws InterruptedException If the thread is interrupted during execution of this function.
-   * @throws DeepLException If the output path is occupied or its directory does not exist (checked
-   *     before the export job is created), writing the file fails (with the I/O error as cause),
-   *     the timeout is exceeded, the export fails, or any error occurs while communicating with the
-   *     DeepL API.
+   * @throws DeepLException If the timeout is exceeded, the export fails, or any error occurs while
+   *     communicating with the DeepL API.
    * @see DeepLClient#exportTranslationMemoryToFilepath(String, File)
    */
   public TranslationMemoryJob exportTranslationMemoryToFilepath(
@@ -2777,11 +2769,7 @@ public TranslationMemoryJob exportTranslationMemoryToFilepath(
         createTranslationMemoryExport(translationMemoryId);
     TranslationMemoryJob job =
         waitUntilTranslationMemoryJobDone(translationMemoryExport.getJobId(), timeout);
-    try {
-      downloadTranslationMemoryExport(job, outputFile);
-    } catch (IOException exception) {
-      throw wrapLocalIOException("Failed to write translation memory export", exception);
-    }
+    downloadTranslationMemoryExport(job, outputFile);
     return job;
   }
 
@@ -2831,11 +2819,7 @@ public TranslationMemoryJob exportTranslationMemoryToFilepath(
         createTranslationMemoryExport(translationMemoryId);
     TranslationMemoryJob job =
         waitUntilTranslationMemoryJobDone(translationMemoryExport.getJobId(), timeout);
-    try {
-      downloadTranslationMemoryExport(job, outputStream);
-    } catch (IOException exception) {
-      throw wrapLocalIOException("Failed to write translation memory export", exception);
-    }
+    downloadTranslationMemoryExport(job, outputStream);
     return job;
   }
 
@@ -2922,48 +2906,25 @@ private static String translationMemoryJobId(TranslationMemoryJob job)
   /**
    * Reads a TMX file for import; a missing file is an argument error, raised before any request.
    */
-  private static byte[] readTranslationMemoryFile(@Nullable File inputFile)
-      throws DeepLException, InterruptedException {
+  private static byte[] readTranslationMemoryFile(@Nullable File inputFile) throws IOException {
     if (inputFile == null || !inputFile.exists()) {
       throw new IllegalArgumentException("inputFile must be an existing file");
     }
-    try {
-      return Files.readAllBytes(inputFile.toPath());
-    } catch (IOException exception) {
-      throw wrapLocalIOException("Failed to read translation memory file", exception);
-    }
+    return Files.readAllBytes(inputFile.toPath());
   }
 
   /** Checks the output file of an export so a bad path fails before the export job is created. */
-  private static void checkExportOutputFile(@Nullable File outputFile) throws DeepLException {
+  private static void checkExportOutputFile(@Nullable File outputFile) throws IOException {
     if (outputFile == null) {
       throw new IllegalArgumentException("outputFile must not be null");
     }
     if (outputFile.exists()) {
-      throw new DeepLException("File already exists at output path");
+      throw new IOException("File already exists at output path");
     }
     File directory = outputFile.getAbsoluteFile().getParentFile();
     if (directory == null || !directory.isDirectory()) {
-      throw new DeepLException("Directory of output path does not exist");
-    }
-  }
-
-  /**
-   * Wraps a local I/O failure in a {@link DeepLException}; an interrupted I/O operation is reported
-   * as {@link InterruptedException} instead, as caller cancellation is never wrapped.
-   */
-  private static DeepLException wrapLocalIOException(String message, IOException exception)
-      throws InterruptedException {
-    boolean interrupted =
-        exception instanceof java.nio.channels.ClosedByInterruptException
-            || (exception instanceof InterruptedIOException
-                && !(exception instanceof java.net.SocketTimeoutException));
-    if (interrupted) {
-      InterruptedException interruptedException = new InterruptedException(exception.getMessage());
-      interruptedException.initCause(exception);
-      throw interruptedException;
+      throw new FileNotFoundException("Directory of output path does not exist");
     }
-    return new DeepLException(message + ": " + exception.getMessage(), exception);
   }
 
   /** Extracts the ID of the given Spoken Terms collection. */

deepl-java/src/main/java/com/deepl/api/Translator.java

@@ -330,12 +330,10 @@ public List<GlossaryLanguagePair> getGlossaryLanguages()
    * @param options Options influencing translation.
    * @return Status when document translation completed, this allows the number of billed characters
    *     to be queried.
-   * @throws IllegalArgumentException If the input file does not exist; no request is sent.
-   * @throws DocumentTranslationException If the output path is occupied, a file cannot be opened,
-   *     any error occurs while communicating with the DeepL API, or the thread is interrupted
-   *     during execution of this function. The exception includes the document handle that may be
-   *     used to retrieve the document, if the document was uploaded.
-   * @throws IOException Not thrown; declared for compatibility.
+   * @throws IOException If the output path is occupied or the input file does not exist.
+   * @throws DocumentTranslationException If any error occurs while communicating with the DeepL
+   *     API, or if the thread is interrupted during execution of this function. The exception
+   *     includes the document handle that may be used to retrieve the document.
    */
   public DocumentStatus translateDocument(
       File inputFile,
@@ -344,25 +342,17 @@ public DocumentStatus translateDocument(
       String targetLang,
       @Nullable DocumentTranslationOptions options)
       throws DocumentTranslationException, IOException {
-    if (!inputFile.exists()) {
-      throw new IllegalArgumentException("Input file does not exist: " + inputFile.getPath());
-    }
     // Checked before the try block: its handler deletes the output file.
     if (outputFile.exists()) {
-      throw new DocumentTranslationException(
-          "File already exists at output path: " + outputFile.getPath(), null, null);
+      throw new IOException("File already exists at output path");
     }
     try (InputStream inputStream = new FileInputStream(inputFile);
         OutputStream outputStream = new FileOutputStream(outputFile)) {
       return translateDocument(
           inputStream, inputFile.getName(), outputStream, sourceLang, targetLang, options);
-    } catch (DocumentTranslationException exception) {
+    } catch (Exception exception) {
       outputFile.delete();
       throw exception;
-    } catch (IOException exception) {
-      outputFile.delete();
-      throw new DocumentTranslationException(
-          "Error occurred during document translation: " + exception.getMessage(), exception, null);
     }
   }