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.
+ * + *Порог определяется API-пробой (возврат {@code getMethod("getNextEntry")}), + * а не разбором строки версии: {@code getImplementationVersion()} бывает + * {@code null} в shaded/uber-jar сборках, а проба ловит ровно тот бинарный + * контракт, который реально ломается.
+ */ +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, раздел «Библиотека»)."; + } +} diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java new file mode 100644 index 0000000..3ea6ad1 --- /dev/null +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/DependencyGuardTest.java @@ -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()); + } +}