# 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.