#1878: CanonicalFileUtils.java

Утилита нормализации путей к файлам, которая разрешает символические ссылки, устраняет компоненты пути .. и ., а также нормализует разделители пути через File.getCanonicalPath(). Корректно обрабатывает ошибки ввода-вывода, возвращаясь к getAbsolutePath(). Предоставляет перегрузки на основе строк и объектов File для разрешения пути. Используется везде, где ProjectForge необходимо сравнивать пути к файлам или обеспечивать единообразное представление пути.

Импорты

• java.io.File — абстракция файла JDK
• java.io.IOException — проверяемое исключение от getCanonicalPath()
• org.slf4j.Logger — журналирование ошибок при сбоях ввода-вывода

Основные операции

1. absolutePath(File file) → String

Возвращает канонический путь файла в виде строки. Если getCanonicalPath() выбрасывает IOException (например, файл не существует и файловая система не может разрешить его каноническую форму), возвращается getAbsolutePath() и ошибка записывается в журнал.

2. absolute(File file) → File

Та же логика, но возвращает объект File через getCanonicalFile() / getAbsoluteFile().

3. absolute(String path) → File

Удобная перегрузка, которая оборачивает строковый путь в new File(path) и делегирует выполнение absolute(File).

Почему канонический путь?

Метод Java File.getCanonicalPath() предоставляет несколько гарантий, которых нет у getAbsolutePath():

• Разрешение символических ссылок: В Unix-системах символические ссылки разрешаются до их целевых объектов
• Нормализация: . (текущий каталог) и .. (родительский каталог) разрешаются
• Нормализация регистра файловой системы: В файловых системах без учёта регистра (Windows, macOS) регистр пути соответствует фактической записи файловой системы
• Удаление избыточных разделителей: // схлопывается

Это критически важно для операций, чувствительных к безопасности, где пути из пользовательского ввода должны сравниваться с разрешёнными путями — два разных строковых представления могут ссылаться на один и тот же файл (например, /home/user/../user/file и /home/user/file).

Стратегия обработки ошибок

Класс использует шаблон плавной деградации: если каноническое разрешение не удаётся (IOException), он возвращается к абсолютному пути и записывает ошибку в журнал. Это важно, поскольку getCanonicalPath() может выбросить IOException по причинам, не зависящим от приложения (например, права доступа к файловой системе, проблемы с монтированием NFS или отсутствие файла). Запасной вариант гарантирует, что приложение продолжит работу, хотя и с потенциально ненормализованным путём.

Обработка null

Все методы корректно обрабатывают входной null — возвращают null без выбрасывания NullPointerException. Это упрощает код вызывающего, устраняя необходимость проверок на null перед вызовом утилиты.

Контекст использования в ProjectForge

CanonicalFileUtils используется в таких сценариях, как:

• Загрузка/скачивание файлов: Нормализация указанных пользователем путей к файлам для хранения
• Загрузка конфигурационных файлов: Разрешение путей к конфигурационным файлам, которые могут содержать относительные ссылки
• Сравнение путей: Определение, ссылаются ли два пути на один и тот же файл (например, обнаружение дублирующихся загрузок файлов)
• Проверки безопасности: Обеспечение того, чтобы запрошенный путь к файлу не выходил за пределы базового каталога через обход ..
• Мастер настройки: Разрешение выбранных пользователем каталогов (класс появляется в истории git, связанной с мастером настройки)

868d6abb7 2025 -> 2026
63081666f Заголовки исходных файлов: 2024 -> 2025.
b6092df09 Авторские права 2023 -> 2024
ab45d51fa Авторские права 2001-2022 -> 2001-2023.
5f7ef41b8 Авторские права 2021 -> 2022
ceb63e8a1 Заголовок исходного кода: (C) 2001-2021.
7c79f1922 Авторские права в заголовке исходного кода -> 2020.
bd25a85fb WIP: Мастер настройки (Swing и Lanterna)