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

76 lines
4.3 KiB
Markdown

# API библиотеки
Публичный API мал и стабилен: два сервисных класса, один record, пять видов ошибок.
Javadoc каждого члена — [apidocs](/apidocs/index.html).
## `WordPdfConverter`
```java
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`
Те же проверки входа **без рендера** — например, для валидации загрузки до очереди:
```java
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`
```java
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-провайдер (см. [первые шаги](getting-started.md)) — иначе текст
предупреждений попадает в PDF.