Files
java-word-pdf/docs/library/api.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

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.