fix(core): DependencyGuard — понятная ошибка при старой commons-compress у потребителя #56
@@ -51,7 +51,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр
|
|||||||
|---|---|
|
|---|---|
|
||||||
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)|
|
|`wordpdf-core/src/main/java/ru/pjandro/wordpdf/`|публичный API: `WordPdfConverter`, `WordPdfValidator` (перегрузки `checkInput`/`checkPageCount` и `validate(byte[], ConvertOptions)` — полная цепочка; без зависимости от docx4j), `ConversionException`, `ValidationException` (наследник — «вход некорректен»), `DrawingFoundException` (`enum Kind {CHARTS, SMARTART, OLE}` — отказ по error-флагу), `WordPdfSettings` (константы-дефолты: `MAX_INPUT_MB=5`, `MAX_PAGES=100`, защитные `MAX_DECOMPRESSED_MB=200`/`MAX_ZIP_ENTRIES=8192`, `ERROR_ON_CHARTS/SMARTART/OLE=false`), `ConvertOptions` (record: errorOnCharts, errorOnSmartArt, errorOnOle, maxMb, maxPages)|
|
||||||
|`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)|
|
|`…/wordpdf/fonts/`|`BundledFonts` (реестр/выгрузка TTF, `families()`, `FALLBACK_FAMILY`), `BundledFontMapper` (алиасы MS→open-source, self-map, DISPLAY_NAMES, public-хук `bundledFamily`), `GlyphFont` (глиф-движок fontbox: метрики/глифы без java.awt.Font)|
|
||||||
|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)|
|
|`…/wordpdf/internal/`|7 байтовых нормализаторов + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка совместимости commons-compress, шаг 0 `convertToStream`) (классы `public` — вызываются из родительского пакета; публичные члены только `normalize`/`STEP`/`declare`/`DependencyGuard.check`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)`)|
|
||||||
|`…/wordpdf/internal/chart/`|17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)|
|
|`…/wordpdf/internal/chart/`|17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer`)|
|
||||||
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|
|`wordpdf-core/src/main/resources/fonts/`|30 TTF + 3 лицензии — бинарные фикстуры, часть jar|
|
||||||
|`wordpdf-core/src/test/resources/samples/`|13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py`|
|
|`wordpdf-core/src/test/resources/samples/`|13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py`|
|
||||||
@@ -127,7 +127,7 @@ gateway). Кеш раннеров — сервер act_runner (серверна
|
|||||||
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
|
- Ошибки публичного API — только `ConversionException extends RuntimeException`; внутренние исключения оборачиваются на границе. В chart — деградация вместо падения.
|
||||||
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться).
|
- Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: `Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx`) — новый фикс оформлять так же (в существующем main-коде convention соблюдён лишь частично — `SymbolFontNormalizer`, `WordPdfValidator`, `Surface3dPainter` и классы app; новые правки обязаны ссылаться).
|
||||||
- Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
|
- Константы UPPER_SNAKE с числовыми эталонными значениями (`PIE_DEPTH`, `MAX_PAGES`); начертания `V_REGULAR/V_BOLD/...`; модели — `record`; размеры в chart — в пунктах, растр × `DPI/72`.
|
||||||
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
|
- Классы в `internal` — `public` (иначе родительский пакет не вызвал бы), но публичные члены наружу только `normalize`/`STEP`/`declare`/`DrawingPreRenderer.run`/`DependencyGuard.check` (`rewrite`, карты — package-private); в `wordpdf-app` всё package-private кроме `WordPdfApplication`.
|
||||||
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`.
|
- Тестовые методы: регрессионные — `объект_условие` через underscore (`ruPlain_cyrillicAndStyles`, `checkInput_bytesOverLimit`, `noKey_rejected`); чистые юниты — camelCase (`pageFieldBecomesFldSimple`, `splitsRunForUncoveredGlyph`); оба стиля разрешает PMD-паттерн `junit5TestPattern`.
|
||||||
|
|
||||||
## Important Files
|
## Important Files
|
||||||
|
|||||||
@@ -130,6 +130,50 @@ Files.write(Path.of("out.pdf"), pdf);
|
|||||||
больше ста) бросают `ConversionException`. Работа с файлами — забота
|
больше ста) бросают `ConversionException`. Работа с файлами — забота
|
||||||
вызывающего: ядро пути не принимает.
|
вызывающего: ядро пути не принимает.
|
||||||
|
|
||||||
|
#### Зависимость commons-compress (интеграция в чужой проект)
|
||||||
|
|
||||||
|
Ядру (через docx4j) нужен `org.apache.commons:commons-compress >= 1.25.0`,
|
||||||
|
рекомендована `1.28.0` — версию закрепляет POM ядра. Симптом старой версии в
|
||||||
|
classpath потребителя — `NoSuchMethodError:
|
||||||
|
org.apache.commons.compress.archivers.zip.ZipArchiveEntry
|
||||||
|
org.apache.commons.compress.archivers.zip.ZipArchiveInputStream.getNextEntry()`.
|
||||||
|
До входа в docx4j теперь срабатывает guard: `ConversionException` с текстом,
|
||||||
|
объясняющим, какую версию закрепить.
|
||||||
|
|
||||||
|
**Maven.** BOM (например, Spring Boot 3.x) пинит свою версию commons-compress,
|
||||||
|
а `dependencyManagement` потребителя перекрывает транзитивные версии
|
||||||
|
(«nearest wins») — закреплять нужно именно в нём:
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependencyManagement>
|
||||||
|
<dependencies>
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.apache.commons</groupId>
|
||||||
|
<artifactId>commons-compress</artifactId>
|
||||||
|
<version>1.28.0</version>
|
||||||
|
</dependency>
|
||||||
|
</dependencies>
|
||||||
|
</dependencyManagement>
|
||||||
|
```
|
||||||
|
|
||||||
|
Диагностика: `mvn dependency:tree -Dincludes=org.apache.commons:commons-compress`.
|
||||||
|
|
||||||
|
**Gradle.** По умолчанию Gradle выбирает максимальную версию и конфликт
|
||||||
|
разрешает сам — guard не сработает и не нужен. Понижает версию только явный
|
||||||
|
`constraints` / `platform` / `resolutionStrategy`: уберите понижение либо
|
||||||
|
закрепите нужную версию:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
dependencies {
|
||||||
|
constraints {
|
||||||
|
implementation("org.apache.commons:commons-compress:1.28.0")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(либо `resolutionStrategy.force("org.apache.commons:commons-compress:1.28.0")`).
|
||||||
|
Диагностика: `gradle dependencies --configuration runtimeClasspath`.
|
||||||
|
|
||||||
### Веб-интерфейс и контейнеры (podman)
|
### Веб-интерфейс и контейнеры (podman)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -23,6 +23,9 @@
|
|||||||
|
|
||||||
<!-- docx4j: последняя стабильная версия на Maven Central -->
|
<!-- docx4j: последняя стабильная версия на Maven Central -->
|
||||||
<docx4j.version>17.3.2</docx4j.version>
|
<docx4j.version>17.3.2</docx4j.version>
|
||||||
|
<!-- commons-compress: версию декларирует docx4j-core 17.3.2 (1.28.0);
|
||||||
|
не завышать — версия привязана к docx4j, а не к свежести -->
|
||||||
|
<commons-compress.version>1.28.0</commons-compress.version>
|
||||||
<slf4j.version>2.0.20</slf4j.version>
|
<slf4j.version>2.0.20</slf4j.version>
|
||||||
|
|
||||||
<!-- Spring Boot + springdoc: последние стабильные на Maven Central -->
|
<!-- Spring Boot + springdoc: последние стабильные на Maven Central -->
|
||||||
@@ -74,6 +77,13 @@
|
|||||||
<artifactId>docx4j-export-fo</artifactId>
|
<artifactId>docx4j-export-fo</artifactId>
|
||||||
<version>${docx4j.version}</version>
|
<version>${docx4j.version}</version>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
<!-- Прямая зависимость ядра (DependencyGuard) + нижний порог
|
||||||
|
docx4j 17.3.2 — 1.25.0; в Boot-BOM 4.1.1 не управляется -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.apache.commons</groupId>
|
||||||
|
<artifactId>commons-compress</artifactId>
|
||||||
|
<version>${commons-compress.version}</version>
|
||||||
|
</dependency>
|
||||||
<!-- Без настроенного slf4j docx4j печатает предупреждение прямо в PDF -->
|
<!-- Без настроенного slf4j docx4j печатает предупреждение прямо в PDF -->
|
||||||
<dependency>
|
<dependency>
|
||||||
<groupId>org.slf4j</groupId>
|
<groupId>org.slf4j</groupId>
|
||||||
|
|||||||
@@ -49,6 +49,13 @@
|
|||||||
<groupId>org.slf4j</groupId>
|
<groupId>org.slf4j</groupId>
|
||||||
<artifactId>jcl-over-slf4j</artifactId>
|
<artifactId>jcl-over-slf4j</artifactId>
|
||||||
</dependency>
|
</dependency>
|
||||||
|
<!-- Используется DependencyGuard (проверка совместимости classpath);
|
||||||
|
транзитивно приходит от docx4j-core, объявлена явно как контракт
|
||||||
|
интеграции — потребитель видит её в своём дереве зависимостей -->
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.apache.commons</groupId>
|
||||||
|
<artifactId>commons-compress</artifactId>
|
||||||
|
</dependency>
|
||||||
|
|
||||||
<!-- ============ Тесты ============ -->
|
<!-- ============ Тесты ============ -->
|
||||||
<dependency>
|
<dependency>
|
||||||
|
|||||||
@@ -11,6 +11,7 @@ import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
|
|||||||
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
|
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
|
||||||
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
import ru.pjandro.wordpdf.fonts.BundledFonts;
|
||||||
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
|
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
|
||||||
|
import ru.pjandro.wordpdf.internal.DependencyGuard;
|
||||||
import ru.pjandro.wordpdf.internal.DocxNormalizer;
|
import ru.pjandro.wordpdf.internal.DocxNormalizer;
|
||||||
import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer;
|
import ru.pjandro.wordpdf.internal.DocxOnOffNormalizer;
|
||||||
import ru.pjandro.wordpdf.internal.FieldNormalizer;
|
import ru.pjandro.wordpdf.internal.FieldNormalizer;
|
||||||
@@ -116,10 +117,16 @@ public final class WordPdfConverter {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток.
|
* Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. Шаг 0 — проверка
|
||||||
|
* совместимости commons-compress в classpath потребителя (DependencyGuard):
|
||||||
|
* без неё старая версия библиотеки дала бы мутный NoSuchMethodError внутри docx4j.
|
||||||
*/
|
*/
|
||||||
private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options,
|
private static void convertToStream(byte[] rawDocxBytes, String title, ConvertOptions options,
|
||||||
OutputStream os) throws Exception {
|
OutputStream os) throws Exception {
|
||||||
|
// 0. Совместимость commons-compress: docx4j требует ковариантный
|
||||||
|
// ZipArchiveInputStream.getNextEntry() (>= 1.25.0); ниже — понятный
|
||||||
|
// ConversionException с инструкцией вместо NoSuchMethodError.
|
||||||
|
DependencyGuard.check();
|
||||||
// 1. Маппер шрифтов. Порядок важен: конструктор запускает
|
// 1. Маппер шрифтов. Порядок важен: конструктор запускает
|
||||||
// обнаружение системных шрифтов, затем бандл-шрифты из jar
|
// обнаружение системных шрифтов, затем бандл-шрифты из jar
|
||||||
// регистрируются поверх них (имеют приоритет).
|
// регистрируются поверх них (имеют приоритет).
|
||||||
|
|||||||
@@ -0,0 +1,69 @@
|
|||||||
|
package ru.pjandro.wordpdf.internal;
|
||||||
|
|
||||||
|
import org.apache.commons.compress.archivers.zip.ZipArchiveEntry;
|
||||||
|
import org.apache.commons.compress.archivers.zip.ZipArchiveInputStream;
|
||||||
|
import ru.pjandro.wordpdf.ConversionException;
|
||||||
|
|
||||||
|
import java.lang.reflect.Method;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Проверка совместимости commons-compress в classpath потребителя.
|
||||||
|
*
|
||||||
|
* <p>docx4j читает zip-контейнер docx через
|
||||||
|
* {@code org.docx4j.openpackaging.io3.stores.ZipPartStore}, который вызывает
|
||||||
|
* ковариантный {@code ZipArchiveInputStream.getNextEntry(): ZipArchiveEntry}
|
||||||
|
* — он появился только в commons-compress 1.25.0. Если у потребителя старая
|
||||||
|
* версия (BOM, например Spring Boot 3.x, или nearest-wins в Maven навязали
|
||||||
|
* понижение), конвертация падала мутным {@code NoSuchMethodError} внутри
|
||||||
|
* docx4j. Guard бросает {@link ConversionException} с текстом-инструкцией
|
||||||
|
* до входа в docx4j.</p>
|
||||||
|
*
|
||||||
|
* <p>Порог определяется API-пробой (возврат {@code getMethod("getNextEntry")}),
|
||||||
|
* а не разбором строки версии: {@code getImplementationVersion()} бывает
|
||||||
|
* {@code null} в shaded/uber-jar сборках, а проба ловит ровно тот бинарный
|
||||||
|
* контракт, который реально ломается.</p>
|
||||||
|
*/
|
||||||
|
public final class DependencyGuard {
|
||||||
|
|
||||||
|
private DependencyGuard() {
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Бросает {@link ConversionException}, если commons-compress в classpath
|
||||||
|
* несовместим с docx4j 17.3.2 (нет ковариантного {@code getNextEntry},
|
||||||
|
* т.е. версия ниже 1.25.0, либо библиотека отсутствует).
|
||||||
|
*/
|
||||||
|
public static void check() {
|
||||||
|
String reason = incompatibleReason();
|
||||||
|
if (reason != null) {
|
||||||
|
throw new ConversionException(reason);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Причина отказа или {@code null}, если classpath совместим.
|
||||||
|
* Package-private хук для юнит-теста (негативную ветку surefire покрыть
|
||||||
|
* нельзя — одна версия jar на тестовом classpath, см. DependencyGuardTest).
|
||||||
|
*/
|
||||||
|
static String incompatibleReason() {
|
||||||
|
String found;
|
||||||
|
try {
|
||||||
|
Method m = ZipArchiveInputStream.class.getMethod("getNextEntry");
|
||||||
|
if (ZipArchiveEntry.class.equals(m.getReturnType())) {
|
||||||
|
return null; // >= 1.25.0: ковариантный getNextEntry на месте
|
||||||
|
}
|
||||||
|
String v = ZipArchiveInputStream.class.getPackage().getImplementationVersion();
|
||||||
|
found = v == null ? "версия не определена" : v;
|
||||||
|
} catch (NoSuchMethodException e) {
|
||||||
|
found = "версия не определена"; // нет даже getNextEntry — доисторическая сборка
|
||||||
|
} catch (NoClassDefFoundError e) {
|
||||||
|
return "В classpath отсутствует org.apache.commons:commons-compress — "
|
||||||
|
+ "docx4j требует версию 1.28.0 (минимум 1.25.0).";
|
||||||
|
}
|
||||||
|
return "Несовместимая версия commons-compress в classpath (найдена: " + found
|
||||||
|
+ "): docx4j требует >= 1.25.0, рекомендована 1.28.0. Старую версию обычно"
|
||||||
|
+ " навязывает BOM или nearest-wins. Закрепите org.apache.commons:commons-compress"
|
||||||
|
+ " версии 1.28.0: Maven — запись в dependencyManagement, Gradle — constraints"
|
||||||
|
+ " или resolutionStrategy.force (см. README, раздел «Библиотека»).";
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,25 @@
|
|||||||
|
package ru.pjandro.wordpdf.internal;
|
||||||
|
|
||||||
|
import org.junit.jupiter.api.Test;
|
||||||
|
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
|
||||||
|
import static org.junit.jupiter.api.Assertions.assertNull;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Guard на тестовом classpath (commons-compress 1.28.0) — no-op.
|
||||||
|
* Негативная ветка (старая версия jar) surefire-покрытию недоступна — одна
|
||||||
|
* версия jar на classpath; проверена эмпирически подменой jar в classpath
|
||||||
|
* прогона (1.21 → ConversionException, 1.25.0/1.28.0 → OK).
|
||||||
|
*/
|
||||||
|
class DependencyGuardTest {
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void checkPassesOnCurrentClasspath() {
|
||||||
|
assertDoesNotThrow(DependencyGuard::check);
|
||||||
|
}
|
||||||
|
|
||||||
|
@Test
|
||||||
|
void reasonNullOnCurrentClasspath() {
|
||||||
|
assertNull(DependencyGuard.incompatibleReason());
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user