#1877: CSVWriter.java [RU]

Импорты

java.io.PrintWriter / java.io.Writer — Текстовый вывод
java.text.DateFormat / SimpleDateFormat — Форматирование дат для CSV-колонок с датами
java.util.Date — Тип значения даты
java.util.TimeZone — Часовой пояс UTC для форматирования дат

Конфигурация

Настройка	По умолчанию	Сеттер
Разделитель CSV	`';'` (точка с запятой — европейская конвенция)	`setCsvSeparator(char)`
Окончание строки	`"\n"` (перевод строки Unix)	`setCr(String)`
Формат даты	`"yyyy-MM-dd HH:mm:ss.SSS"`	`setDateFormat(DateFormat)`
Часовой пояс даты	UTC	Жёстко задан в конструкторе

Плавный (Fluent) API построителя

Все методы write() возвращают this (экземпляр CSVWriter), что позволяет выстраивать цепочки вызовов:

csvWriter.write("Имя").write("Возраст").write(42L).writeEndOfLine();

Типизированные перегрузки Write

Метод	Форматирование	Экранирование
`write(String s)`	Исходная строка с экранированием `"` в `""` (удвоение)	Всегда обёрнуто в `"..."` — следует правилам экранирования RFC 4180
`write(long value)`	Прямой числовой вывод через `PrintWriter.print()`	Нет — числа без кавычек
`write(Date value)`	Форматируется через `dateFormat.format()` в UTC	Обёрнуто в кавычки — даты могут содержать пробелы или спецсимволы
`write(Object value)`	Запасной вариант: `String.valueOf(value)`	Нет — общие объекты без кавычек (рискованно для объектов с запятыми/кавычками)

Алгоритм экранирования (запись строк)

Метод write(String) реализует правильное экранирование CSV согласно RFC 4180:

Выводит разделитель, если это не первая запись в строке (управляется writeSeparator() с флагом firstEntry)
Выводит открывающую двойную кавычку (")
Перебирает каждый символ строки
Если символ — двойная кавычка ("), выводит её дважды ("") — стандартная escape-последовательность CSV
Выводит все остальные символы как есть
Выводит закрывающую двойную кавычку (")

Запись строк

writeLine(Object[] values) — Записывает все значения из массива, затем вызывает writeEndOfLine()
writeEndOfLine() — Выводит настроенное окончание строки (по умолчанию \n) и сбрасывает firstEntry = true

Логика разделителя (writeSeparator)

Булев флаг firstEntry отслеживает, находимся ли мы в начале строки:

Если firstEntry == true: устанавливается в false (первая ячейка — разделитель не нужен)
Если firstEntry == false: перед значением ячейки выводится символ-разделитель

Это классический паттерн отслеживания состояния для вывода с разделителями.

Интеграция с CSVParser

CSVWriter определяет DEFAULT_CSV_SEPARATOR_CHAR = ';' как публичную константу, на которую ссылается CSVParser для обеспечения согласованного разделителя по умолчанию между читателем и писателем.

Сравнение с современными CSV-библиотеками

Эта реализация намеренно минималистична по сравнению с Apache Commons CSV или OpenCSV:

Нет маппинга заголовков (это обрабатывается CSVParser.parseHeadCols())
Нет автоматического преобразования типов (вызывающие форматируют значения перед записью)
Нет оптимизаций для потоковой передачи/больших файлов (запись напрямую в Writer)
Нет поддержки различных стратегий экранирования (все строки экранируются; числа — никогда)

Простота отражает его происхождение как специализированного инструмента для экспорта данных ProjectForge, а не универсальной CSV-библиотеки.

Метод write(Object) НЕ экранирует вывод — он вызывает String.valueOf(value) и записывает напрямую. Если toString() объекта возвращает строку, содержащую запятые, точки с запятой или переводы строк, результирующий CSV будет повреждён. Это приемлемо, поскольку ожидается, что вызывающие будут использовать типизированные перегрузки.

Вывод дат использует часовой пояс UTC — даты нормализуются к UTC перед форматированием. Это осознанный выбор для обмена данными: он устраняет неоднозначность часовых поясов при экспорте. Формат "yyyy-MM-dd HH:mm:ss.SSS" похож на ISO 8601, но использует пробел в качестве разделителя вместо 'T'.

#1877: `CSVWriter.java`

Архитектура