はじめに (対象読者・この記事でわかること)

このページは、JavaでWebアプリやデスクトップアプリのファイル添付ダウンロード機能を実装しようとしている初心者〜中級者向けに書かれています。
ダウンロード処理中に頻繁に目にするFileNotFoundExceptionの発生原因を体系的に理解し、例外がスローされても安全に処理を継続できるコードを書けるようになることを目的としています。
また、今回取り上げるシナリオは「ユーザーが添付ファイルをクリックしたらサーバ上のファイルを取得し、ローカルに保存する」典型的なケースです。実務で遭遇することの多いエラーを未然に防ぐヒントが得られるでしょう。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。
- Java SE 8 以上の基本的な文法と例外処理
- java.io パッケージ（FileInputStream、FileOutputStream など）の概要
- HTTP クライアントライブラリ（例: java.net.HttpURLConnection または Apache HttpClient）の簡単な使い方

FileNotFoundException の概要とダウンロード処理における落とし穴

Java でファイルを扱う際に最も直感的に投げられる例外が FileNotFoundException です。「指定したパスにファイルが存在しない」という意味だけでなく、「ディレクトリが作成できない」や「読み取り権限が不足している」といったケースでも同例外が利用されます。
添付ファイルをダウンロードするシナリオでは、次のような原因が典型的です。

  1. サーバ側のパスが誤っている
    URL パラメータや設定ファイルに誤字があると、サーバが返すステータスは 404 ですが、クライアント側で InputStream を取得しようとすると FileNotFoundException が発生します。

  2. ローカルの保存先ディレクトリが存在しない
    new FileOutputStream("downloaded/files/report.pdf") のように、途中のディレクトリ downloaded/files が事前に作成されていないと例外が投げられます。

  3. ファイル名に使用できない文字が含まれる
    Windows では * ? < > | などがファイル名に使えません。サーバから取得したそのままの名前を保存しようとすると FileNotFoundException が発生することがあります。

  4. 権限不足
    読み込み権限が無いディレクトリや、書き込み禁止の領域に保存しようとした場合も同例外がスローされます。

このように、例外は単に「ファイルが無い」だけでなく、環境や権限の問題も含んでいることを意識しておくことが重要です。次の章では、これらの落とし穴を回避する具体的な実装手順を示します。

実装例と例外対策：添付ファイルを安全にダウンロードする手順

以下では、HttpURLConnection を使用したシンプルなダウンロード実装を例に、例外が起きたときの対策を段階的に解説します。コードは Java 11 以降でも問題なく動作しますが、JDK 8 でも同様に利用できます。

ステップ1　ダウンロード先ディレクトリの事前作成とパス正規化

Java

import java.io.File;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

public class DownloadUtil {

    private static final String BASE_DIR = "downloaded/files";

    /** ダウンロード先ディレクトリが存在しなければ作成する */
    public static Path prepareDestination(String fileName) throws IOException {
        // 不正文字を除去（Windows 用に簡易的に置換）
        String sanitized = fileName.replaceAll("[\\\\/:*?\"<>|]", "_");

        Path dir = Paths.get(BASE_DIR);
        if (Files.notExists(dir)) {
            Files.createDirectories(dir);
        }
        return dir.resolve(sanitized);
    }
}
  • Files.createDirectories は階層全体をまとめて作成でき、すでに存在すれば何もしません。
  • ファイル名のサニタイズは必須です。ここでは正規表現で禁止文字をアンダースコアへ置換しています。

ステップ2　HTTP 接続確立とストリーム取得

Java

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;

public class Downloader {

    public static void downloadFile(String fileUrl, String destFileName) {
        HttpURLConnection conn = null;
        try (InputStream in = openConnection(fileUrl);
             OutputStream out = new BufferedOutputStream(
                     Files.newOutputStream(DownloadUtil.prepareDestination(destFileName)))) {

            byte[] buffer = new byte[8192];
            int bytesRead;
            while ((bytesRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, bytesRead);
            }
            System.out.println("Download completed: " + destFileName);
        } catch (FileNotFoundException e) {
            // 例外の根本原因を判定してログに残す
            System.err.println("[Error] ファイルが見つかりません: " + e.getMessage());
            // 例外を再スローしないで処理を続行するか、代替処理へ
        } catch (IOException e) {
            System.err.println("[Error] I/O エラー: " + e.getMessage());
        } finally {
            if (conn != null) {
                conn.disconnect();
            }
        }
    }

    private static InputStream openConnection(String fileUrl) throws IOException {
        URL url = new URL(fileUrl);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("GET");
        conn.setConnectTimeout(15_000);
        conn.setReadTimeout(30_000);

        int status = conn.getResponseCode();
        if (status != HttpURLConnection.HTTP_OK) {
            throw new FileNotFoundException("HTTP " + status + " for URL: " + fileUrl);
        }
        return conn.getInputStream();
    }
}

コードのポイント

項目 内容
try-with-resources InputStream と OutputStream を自動的にクローズし、リソースリークを防止
FileNotFoundException の捕捉 HTTP ステータスが 404 のときは自前で FileNotFoundException をスローし、上位で統一的に処理
バッファサイズ 8192 バイト 標準的な I/O バッファで、パフォーマンスとメモリ使用量のバランスが良い
Files.newOutputStream Path オブジェクトから直接ストリーム取得、StandardOpenOption.CREATE が暗黙的に適用される

ハマった点やエラー解決

  1. FileNotFoundException がディレクトリ作成前に発生
    - 原因: prepareDestination でディレクトリ作成を忘れたケース。
    - 解決策: Files.createDirectories を必ず呼び出すように統一したメソッドに切り出した。

  2. ファイル名に全角スペースや改行が含まれる
    - 原因: URL エンコードが不完全で、ローカル保存時に "\n" がファイル名に残った。
    - 解決策: URLDecoder.decode でデコードした後、\s+ を単一スペースに正規化し、禁止文字も除去。

  3. HTTPS 接続時に証明書エラーで例外が出る
    - 原因: 社内ネットワークの自己署名証明書。
    - 解決策: HttpsURLConnection.setSSLSocketFactory に自前の TrustManager を設定し、例外を抑制（本番では適切な証明書を導入）。

例外対策のベストプラクティスまとめ

  • 例外は早期に捕捉し、原因をログに残す
    FileNotFoundException のメッセージに HTTP ステータスやローカルパスを含めると、トラブルシューティングが容易になる。

  • ディレクトリとファイル名の事前バリデーション
    Path オブジェクトで Files.isWritable、Files.isReadable をチェックし、権限不足を事前に検出。

  • リトライロジックの導入
    ネットワークの一時的な障害に備えて、RetryTemplate（Spring）や自前のループで 3 回程度リトライする実装を追加すると信頼性が向上する。

  • ユニットテストでエッジケースを網羅
    @TempDir（JUnit5）を利用して、存在しないディレクトリや無効文字列を入れたテストケースを作成し、例外ハンドリングが正しく動作することを検証する。

まとめ

本記事では、Java で添付ファイルのダウンロード中に発生しやすい FileNotFoundException の原因と、事前ディレクトリ作成・ファイル名サニタイズ・例外ハンドリングを組み合わせた安全な実装手順 を解説しました。

  • 原因の把握：パスの誤り・ディレクトリ未作成・不正文字・権限不足が主な要因
  • 対策：Files.createDirectories、サニタイズ、統一的な例外スロー、リトライ実装
  • ベストプラクティス：ログ出力、事前バリデーション、テストでエッジケースを検証

これにより、ダウンロード機能の信頼性が大幅に向上し、ユーザーに対して安定したファイル提供が可能になります。次回は、大容量ファイルのストリーミングダウンロードと進捗表示について掘り下げる予定です。

参考資料