b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
76 lines
4.3 KiB
Markdown
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.
|