- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.3 KiB
API библиотеки
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок. Javadoc каждого члена — apidocs.
WordPdfConverter
public final class WordPdfConverter {
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options)
throws ConversionException;
public static synchronized void warmup();
}
convert— единственный путь конвертации (двухаргументной перегрузки нет). Принимает байты.docxили.doc(маршрутизация по сигнатуре), возвращает байты PDF.title— заголовок PDF.options == null→ValidationException.warmup()— идемпотентный прогрев конвейера; не бросает.
WordPdfValidator
Те же проверки входа без рендера — например, для валидации загрузки до очереди:
public static void checkInput(byte[] docxBytes, long maxMb) throws ValidationException;
public static void validate(byte[] docxBytes, ConvertOptions options) throws ValidationException;
Проверяются: непустота, размер (maxMb), сигнатура (zip/CFB), для docx — контейнер
([Content_Types].xml с типом документа), производные пороги (распаковка, XML,
растры, записи zip), число страниц (lightweight-скан, без docx4j; для .doc —
по сырым байтам мостом).
ConvertOptions
public record ConvertOptions(boolean errorOnCharts, boolean errorOnSmartArt,
boolean errorOnOle, long maxMb, int maxPages) {}
Порядок полей фиксирован. maxMb/maxPages должны быть больше 0. Дефолтов
в ядре нет — значения задаёт вызывающий. Диаграммы/SmartArt конвертируются всегда;
флаги только отменяют конвертацию находкой.
Ошибки
ConversionException (RuntimeException)
├── ValidationException — вход некорректен (не docx/doc, размер, страницы, битый zip…)
├── ChartsFoundException — errorOnCharts и найдены диаграммы
├── SmartArtFoundException — errorOnSmartArt и найден SmartArt
└── OleFoundException — errorOnOle и найдены OLE-объекты
Ловите ConversionException — он покрывает всё; ValidationException — отдельно,
когда хотите различать «пользователь прислал мусор» и «конвертер не смог».
Инвариант параллельности
convert потокобезопасен, но сериализован: все конвертации идут под монитором
класса WordPdfConverter.class — ядро мутирует глобальный реестр шрифтов docx4j
(PhysicalFonts). Параллельные вызовы корректны, но исполняются последовательно;
собственный пул/очередь с отказом при переполнении — забота вызывающего
(так делает wordpdf-app: один воркер, очередь 16).
Шрифты и окружение
- Шрифты выгружаются из jar во временный каталог; реестр после каждой конвертации возвращается к бандлу — встроенные в чужие docx шрифты не «травят» последующие конвертации.
java.awt.Fontне используется (глифы — fontbox напрямую): fontconfig хосту не нужен, контейнер без/etc/fontsработает.- Нужен SLF4J-провайдер (см. первые шаги) — иначе текст предупреждений попадает в PDF.