core: ValidationException вместо ConversionException; удаление pkg-API и переименование checkPageCountLightweight в checkPageCount

This commit is contained in:
Pjandro
2026-10-19 21:30:45 +00:00
parent faf6d048a5
commit f09b629270
11 changed files with 153 additions and 402 deletions
@@ -0,0 +1,22 @@
package ru.pjandro.wordpdf;
/**
* Некорректный вход: {@code null}-байты, размер или число страниц сверх
* лимитов, неразбираемый .docx-контейнер (не zip / битый XML).
*
* <p>Отличается от прочего {@link ConversionException} смыслом: вход плох сам
* по себе, повтор с теми же байтами ничего не изменит. Наследник
* {@code ConversionException} — наружу по-прежнему ловится только он
* (в т.ч. из {@link WordPdfConverter}, который вызывает валидатор сам).
* Регрессия — WordPdfValidatorTest, ConvertControllerTest#corruptNotAZip_rejected.</p>
*/
public class ValidationException extends ConversionException {
public ValidationException(String message) {
super(message);
}
public ValidationException(String message, Throwable cause) {
super(message, cause);
}
}
@@ -59,14 +59,16 @@ public final class WordPdfConverter {
*
* <p>Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[])}
* (null / больше {@link WordPdfSettings#MAX_INPUT_BYTES}), затем число страниц
* ({@link WordPdfSettings#MAX_PAGES}) — при отказе байтов результата нет.
* ({@link WordPdfValidator#checkPageCount(byte[])}, лимит
* {@link WordPdfSettings#MAX_PAGES}) — при отказе байтов результата нет.
*
* @param docxBytes байты .docx
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @return байты готового PDF
* @throws ConversionException при ошибке (битый .docx, размер больше
* {@link WordPdfSettings#MAX_INPUT_BYTES}, результат длиннее
* {@link WordPdfSettings#MAX_PAGES} страниц и т.п.)
* @throws ValidationException некорректный вход: {@code null}, размер больше
* {@link WordPdfSettings#MAX_INPUT_BYTES}, документ длиннее
* {@link WordPdfSettings#MAX_PAGES} страниц
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/
public static byte[] convert(byte[] docxBytes, String title) throws ConversionException {
return convert(docxBytes, title, ConvertOptions.defaults());
@@ -78,16 +80,18 @@ public final class WordPdfConverter {
*
* <p>Вход проверяется валидатором до рендера: {@link WordPdfValidator#checkInput(byte[], long)}
* (null / больше {@code options.maxBytes()}), затем число страниц
* ({@code options.maxPages()}) — при отказе байтов результата нет.
* ({@link WordPdfValidator#checkPageCount(byte[], int)}, лимит
* {@code options.maxPages()}) — при отказе байтов результата нет.
*
* @param docxBytes байты .docx
* @param title заголовок PDF (метаданные); {@code null}/пустая — заголовок не задаётся
* @param options рисование и лимиты входа на этот вызов; {@code null} —
* дефолты (константы {@link WordPdfSettings})
* @return байты готового PDF
* @throws ConversionException при ошибке (битый .docx, размер больше
* {@code options.maxBytes()}, результат длиннее
* {@code options.maxPages()} страниц и т.п.)
* @throws ValidationException некорректный вход: {@code null}, размер больше
* {@code options.maxBytes()}, документ длиннее {@code options.maxPages()}
* страниц
* @throws ConversionException прочие ошибки (битый .docx, ошибка рендера)
*/
public static byte[] convert(byte[] docxBytes, String title, ConvertOptions options) throws ConversionException {
ConvertOptions opts = options == null ? ConvertOptions.defaults() : options;
@@ -96,6 +100,8 @@ public final class WordPdfConverter {
try {
convertToStream(docxBytes, title, opts, bos);
} catch (ConversionException e) {
// ValidationException (отказ валидации входа) — подтип, уходит
// вызывающему без обёртки
throw e;
} catch (Exception e) {
throw new ConversionException("Не удалось конвертировать документ", e);
@@ -139,12 +145,13 @@ public final class WordPdfConverter {
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new ByteArrayInputStream(docxBytes));
try {
// 2.5 Проверка числа страниц по самому .docx: кэш Word
// (docProps/app.xml <Pages>) или нижняя оценка по явным
// разрывам. Делается до рендера, чтобы не тратить время на
// заведомо длинный документ; внутри try — чтобы и на отказе
// отработал finally с чисткой temp-файлов встроенных шрифтов.
WordPdfValidator.checkPageCount(pkg, options.maxPages());
// 2.5 Проверка числа страниц по самому .docx: lightweight-оценка
// по zip (кэш docProps/app.xml <Pages>, явные разрывы, маркеры
// w:lastRenderedPageBreak, включая колонтитулы) — без JAXB-модели.
// Делается до рендера, чтобы не тратить время на заведомо
// длинный документ; внутри try — чтобы и на отказе отработал
// finally с чисткой temp-файлов встроенных шрифтов.
WordPdfValidator.checkPageCount(docxBytes, options.maxPages());
// 3. Привязка маппера: docx4j сопоставляет шрифты документа
// с физическими TTF (учитывая и шрифты, встроенные в docx)
pkg.setFontMapper(mapper);
@@ -1,15 +1,5 @@
package ru.pjandro.wordpdf;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.docx4j.wml.Br;
import org.docx4j.wml.ContentAccessor;
import org.docx4j.wml.P;
import org.docx4j.wml.R;
import org.docx4j.wml.SectPr;
import org.docx4j.wml.STBrType;
import jakarta.xml.bind.JAXBElement;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
@@ -27,9 +17,8 @@ import java.util.zip.ZipInputStream;
* Валидатор ограничений на входной .docx:
* размер входа и число страниц.
*
* <p>Вход валидатора — только {@code byte[]} (или уже загруженный
* {@link WordprocessingMLPackage}): файловых проверок нет, работа с
* файлами — забота вызывающего (приложения).
* <p>Вход валидатора — только {@code byte[]}: файловых проверок нет,
* работа с файлами — забота вызывающего (приложения).
*
* <p>Конвертер {@link WordPdfConverter} вызывает валидатор автоматически,
* но им можно пользоваться и напрямую — например, проверить байты
@@ -55,7 +44,7 @@ import java.util.zip.ZipInputStream;
* <p>Проверка делается <b>до</b> рендера — это позволяет отсекать слишком
* длинные документы, не тратя время на конвертацию.
*
* <p>Все ошибки — {@link ConversionException}.
* <p>Все ошибки — {@link ValidationException} (наследник {@link ConversionException}).
*/
public final class WordPdfValidator {
@@ -65,9 +54,9 @@ public final class WordPdfValidator {
/**
* Проверяет размер байтов входа (для документа, полученного из сети/БД).
*
* @throws ConversionException при {@code null} или превышении лимита
* @throws ValidationException при {@code null} или превышении лимита
*/
public static void checkInput(byte[] docxBytes) throws ConversionException {
public static void checkInput(byte[] docxBytes) throws ValidationException {
checkInput(docxBytes, WordPdfSettings.MAX_INPUT_BYTES);
}
@@ -75,18 +64,18 @@ public final class WordPdfValidator {
* Проверяет размер байтов входа против явного лимита (переопределение
* на вызов, см. {@link ConvertOptions#maxBytes()}).
*
* @throws ConversionException при {@code null} или превышении {@code maxBytes}
* @throws ValidationException при {@code null} или превышении {@code maxBytes}
*/
public static void checkInput(byte[] docxBytes, long maxBytes) throws ConversionException {
public static void checkInput(byte[] docxBytes, long maxBytes) throws ValidationException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного файла");
throw new ValidationException("Не указаны байты входного файла");
}
if (docxBytes.length > maxBytes) {
// дефолтный лимит кратен MiB — сообщение остаётся «... 20 МБ ...»
// дефолтный лимит кратен MiB — сообщение остаётся «... 5 МБ ...»
String limit = maxBytes % (1024 * 1024) == 0
? (maxBytes / (1024 * 1024)) + " МБ"
: maxBytes + " байт";
throw new ConversionException("Файл больше " + limit
throw new ValidationException("Файл больше " + limit
+ ": " + docxBytes.length + " байт > " + maxBytes + " байт");
}
}
@@ -98,32 +87,41 @@ public final class WordPdfValidator {
* {@code docProps/app.xml}). Дешёвый путь для проверки байтов из
* сети/БД до любой работы с библиотекой.
*
* <p>Оценка согласована с {@link #checkPageCount(WordprocessingMLPackage)}
* по всем источникам; на границе лимита оба пути дают одинаковый ответ
* (регрессия — {@code checkPageCountLightweight_agreesWithJaxbPath},
* включая 99/100/101 разрывов). Lightweight-путь дополнительно считает
* разрывы в колонтитулах — он консервативнее, расхождение возможно
* <p>Оценка — максимум трёх нижних оценок: кэша Word в
* {@code docProps/app.xml} ({@code <Pages>}; сам по себе недостоверен —
* в регрессной фикстуре {@code stale-cache.docx} равен 1 при 110
* границах страниц), явных разрывов ({@code w:br type="page"},
* {@code w:pageBreakBefore}, межсекционные {@code w:sectPr} — абзацы
* ищутся рекурсивно, включая ячейки таблиц и контентные контролы
* {@code w:sdt}) и маркеров {@code w:lastRenderedPageBreak} — границ
* страниц, которые Word записал при последнем рендере. Оценка нижняя:
* документ без явных разрывов и без маркеров (никогда не открывался в
* Word) оценивается в 1 страницу независимо от фактической длины —
* такие документы лимит не отсекают. На границе лимита оценка точна
* (регрессия — {@code checkPageCount_limitBoundary},
* включая 99/100/101 разрывов); путь дополнительно считает разрывы в
* колонтитулах — консервативная нижняя оценка, расхождение возможно
* только в сторону завышения.
*
* <p>Не-zip байты не отвергаются: {@code ZipInputStream} доходит до EOF
* без единой записи — молча, оценка «1 страница». Корректность контейнера
* проверяет вызывающий по zip-подписи ({@code ConversionService.validate}
* в приложении; регрессия — {@code ConvertControllerTest#corruptNotAZip_rejected}).
* @throws ConversionException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES}
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@link WordPdfSettings#MAX_PAGES}
*/
public static void checkPageCountLightweight(byte[] docxBytes) throws ConversionException {
checkPageCountLightweight(docxBytes, WordPdfSettings.MAX_PAGES);
public static void checkPageCount(byte[] docxBytes) throws ValidationException {
checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCountLightweight(byte[])}, с явным лимитом
* То же, что {@link #checkPageCount(byte[])}, с явным лимитом
* страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
*
* @throws ConversionException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
* @throws ValidationException при {@code null}, ошибке разбора zip или превышении {@code maxPages}
*/
public static void checkPageCountLightweight(byte[] docxBytes, int maxPages) throws ConversionException {
public static void checkPageCount(byte[] docxBytes, int maxPages) throws ValidationException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного .docx");
throw new ValidationException("Не указаны байты входного .docx");
}
int pages;
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
@@ -145,196 +143,14 @@ public final class WordPdfValidator {
return b == null ? null : new ByteArrayInputStream(b);
}, headerFooter);
} catch (IOException | RuntimeException e) {
throw new ConversionException("Не удалось разобрать байты .docx", e);
throw new ValidationException("Не удалось разобрать байты .docx", e);
}
if (pages > maxPages) {
throw new ConversionException("Документ длиннее " + maxPages
throw new ValidationException("Документ длиннее " + maxPages
+ " страниц: получено не менее " + pages);
}
}
/**
* Считает страницы .docx в байтах и проверяет лимит.
*
* @throws ConversionException при {@code null}, ошибке загрузки или превышении лимита
*/
public static void checkPageCount(byte[] docxBytes) throws ConversionException {
checkPageCount(docxBytes, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCount(byte[])}, с явным лимитом страниц
* (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
*
* @throws ConversionException при {@code null}, ошибке загрузки или
* превышении {@code maxPages}
*/
public static void checkPageCount(byte[] docxBytes, int maxPages) throws ConversionException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного .docx");
}
WordprocessingMLPackage pkg;
try {
pkg = WordprocessingMLPackage.load(new ByteArrayInputStream(docxBytes));
} catch (Exception e) {
throw new ConversionException("Не удалось разобрать байты .docx", e);
}
checkPageCount(pkg, maxPages);
}
/**
* Считает страницы уже загруженного .docx и проверяет лимит.
*
* <p>Число страниц — максимум трёх нижних оценок:
* <ol>
* <li>Кэш Word в {@code docProps/app.xml} ({@code <Pages>}).
* Сам по себе недостоверен: Word может сохранить устаревшее
* значение (в регрессной фикстуре {@code stale-cache.docx}
* кэш равен 1 при 110 границах страниц).</li>
* <li>Явные разрывы: {@code w:br[@w:type='page']},
* {@code w:pageBreakBefore} и {@code w:sectPr} прямо в
* {@code w:body}. Абзацы ищутся не только прямо в {@code w:body},
* но и внутри таблиц, контентных контролов {@code w:sdt}
* (Word держит нумерацию именно в контентном контроле) и
* прочего содержимого, реализующего {@link ContentAccessor}.</li>
* <li>Маркеры {@code w:lastRenderedPageBreak} — границы страниц,
* которые Word записал при последнем рендере. Единственный
* источник оценки для документов без явных разрывов, порванных
* по заполнению.</li>
* </ol>
*
* <p>Оценка остаётся нижней: документ без явных разрывов и без
* маркеров (никогда не открывался в Word) оценивается в 1 страницу
* независимо от фактической длины — такие документы лимит не отсекают.
* @throws ConversionException при превышении {@link WordPdfSettings#MAX_PAGES}
*/
public static void checkPageCount(WordprocessingMLPackage pkg) throws ConversionException {
checkPageCount(pkg, WordPdfSettings.MAX_PAGES);
}
/**
* То же, что {@link #checkPageCount(WordprocessingMLPackage)}, с явным
* лимитом страниц (переопределение на вызов, см. {@link ConvertOptions#maxPages()}).
*
* @throws ConversionException при превышении {@code maxPages}
*/
public static void checkPageCount(WordprocessingMLPackage pkg, int maxPages) throws ConversionException {
if (pkg == null) {
throw new ConversionException("Не указан загруженный .docx");
}
int pages = pageCountOf(pkg);
if (pages > maxPages) {
throw new ConversionException("Документ длиннее " + maxPages
+ " страниц: получено не менее " + pages);
}
}
/**
* Возвращает число страниц: максимум кэша {@code <Pages>}, оценки по
* явным разрывам и оценки по {@code w:lastRenderedPageBreak}.
* Виден только из тестов и пакета.
*/
static int pageCountOf(WordprocessingMLPackage pkg) {
int cached = 0;
try {
if (pkg.getDocPropsExtendedPart() != null) {
org.docx4j.docProps.extended.Properties ext =
pkg.getDocPropsExtendedPart().getContents();
if (ext != null && ext.getPages() != null && ext.getPages() > 0) {
cached = ext.getPages();
}
}
} catch (Exception ignored) {
// docPropsExtended может быть не полностью инициализирован —
// тогда остаётся оценка по разрывам.
}
// getJaxbElement() возвращает null, когда JAXB-разбор части провалился
// (docx4j пишет в лог «Problem with part» и «gives up») — без проверки
// здесь была бы NPE вместо внятной ошибки.
var document = pkg.getMainDocumentPart() == null
? null : pkg.getMainDocumentPart().getJaxbElement();
if (document == null || document.getBody() == null) {
throw new ConversionException("Не удалось разобрать word/document.xml");
}
var body = document.getBody();
var content = body.getContent();
int explicit = 1; // сам документ — минимум одна страница
for (Object child : content) {
// В JAXB-модели в body.getContent() лежат только межсекционные
// sectPr; финальная секция — в body.getSectPr(), её здесь нет.
if (child instanceof SectPr sect && startsNewPage(sect)) {
explicit++;
}
}
explicit += walkForPageBreaks(content);
int lastRendered = countLastRendered(content);
return Math.max(Math.max(cached, explicit), lastRendered + 1);
}
/**
* Обход содержимого на явные разрывы: абзацы ищутся рекурсивно —
* прямо в {@code w:body}, в ячейках таблиц, в контентных контролах
* {@code w:sdt} и прочем содержимом, реализующем {@link ContentAccessor}.
* Элементы модели приходят и напрямую, и обёрнутыми в
* {@link JAXBElement} (например {@code w:tbl} в {@code w:body}) —
* обёртка раскрывается через {@link #unwrap}.
* Считаются {@code w:br type="page"} и {@code pageBreakBefore}
* (по одному на абзац), как и в lightweight-пути.
*/
private static int walkForPageBreaks(List<?> content) {
int count = 0;
for (Object raw : content) {
Object item = unwrap(raw);
if (item instanceof P p) {
if (p.getPPr() != null
&& p.getPPr().getPageBreakBefore() != null
&& p.getPPr().getPageBreakBefore().isVal()) {
count++;
}
for (Object runChild : p.getContent()) {
if (unwrap(runChild) instanceof org.docx4j.wml.R r) {
for (Object innerRaw : r.getContent()) {
if (unwrap(innerRaw) instanceof Br br
&& br.getType() == STBrType.PAGE) {
count++;
}
}
}
}
} else if (item instanceof ContentAccessor ca) {
// w:tbl / w:tr / w:tc / w:sdt / w:sdtContent и т.п.
count += walkForPageBreaks(ca.getContent());
}
}
return count;
}
/** Подсчёт маркеров {@code w:lastRenderedPageBreak} в содержимом. */
private static int countLastRendered(List<?> content) {
int count = 0;
for (Object raw : content) {
Object item = unwrap(raw);
if (item instanceof R.LastRenderedPageBreak) {
count++;
} else if (item instanceof ContentAccessor ca) {
count += countLastRendered(ca.getContent());
}
}
return count;
}
/** Раскрывает обёртку {@link JAXBElement} (docx4j так отдаёт tbl и часть содержимого). */
private static Object unwrap(Object item) {
return item instanceof JAXBElement<?> je ? je.getValue() : item;
}
/** Секция, начинающая новую страницу (continuous — нет). */
private static boolean startsNewPage(SectPr sect) {
return sect.getType() == null
|| sect.getType().getVal() == null
|| !sect.getType().getVal().equals("continuous");
}
/** Поставщик потока по имени части zip; null — части нет. */
private interface PartStream {
InputStream open(String name) throws IOException;
@@ -348,8 +164,7 @@ public final class WordPdfValidator {
/**
* Лёгкий расчёт числа страниц прямо по zip-пакету .docx, без docx4j.
* Та же логика, что у {@link #pageCountOf(WordprocessingMLPackage)}:
* максимум кэша {@code docProps/app.xml <Pages>}, явных разрывов и
* Максимум кэша {@code docProps/app.xml <Pages>}, явных разрывов и
* {@code w:lastRenderedPageBreak}. Считаются все колонтитулы
* ({@code word/header*.xml}, {@code word/footer*.xml}) — там Word тоже
* держит {@code w:br type="page"}.