- docx-нормализаторы: tblInd без w:type = dxa (§17.4.87); явный vanish=false перекрывает стиль (§17.3.2.70); RubyNormalizer снимает обёртку w:ruby и удаляет rubyBaseText; DocxOnOffNormalizer не трогает w:scrollbar; SymbolFontNormalizer читает прямые коды w:sym - мост .doc: borderVal 0x1B→inset; STK_CHARACTER=2 (§2.4.6.5); grpprl toggle + знаковые XAS; ChpxIndex cb=0; PapxIndex cpara + ключ по последнему символу; sprmCIstd reset+preserve; Sections YAS/bkc/pgnStart/gutter/nfc; NPE-гард Lists; BrcMayBeNil = нет границы; emission (w:id, слоты шрифтов, Kul, ISS, header-картинки); OfficeArt 0x46B/TIFF/DIB/второй UID + warn EMF/WMF/PICT; PrcData стоп-обработка; CfbReader бюджет + MUST-поля заголовка (§2.2); FibHeader csw/cslw + cbRgFcLcb; PieceTable aCP-дубли + cbMac - мёртвый код: девять неиспользуемых STEP-констант, недостижимая ветка pgMar - javadoc: исправлены номера секций ECMA-376/MS-DOC/MS-CFB/MS-ODRAW в нормализаторах, chart-пакете, мосту - доки: pipeline.md, repo-map.md, doc-bridge.md, render-limitations.md, AGENTS.md синхронизированы с кодом
21 KiB
читать при правке конвейера
WordPdfConverter/нормализаторов/валидатора. Авторитетно наравне с AGENTS.md.
Шаги конвейера 0–7 (полное «что делает» с обоснованиями)
| # | Шаг | Что делает |
|---|---|---|
| 0 | DependencyGuard.check() |
API-проба ZipArchiveInputStream.getNextEntry() — совместимость commons-compress ≥ 1.25.0; иначе ConversionException с инструкцией вместо мутного NoSuchMethodError внутри docx4j |
| 1 | new BundledFontMapper() → BundledFonts.init() → restrictToBundled() |
Конструктор маппера (static BestMatchingMapper) регистрирует в PhysicalFonts только symbol-шрифты из docx4j-export-fo-fonts-symbol (сканы системы и jar'ов отключены в static-блоке WordPdfConverter гейт-свойствами — всё найденное всё равно выбрасывает restrictToBundled()); init() вызывает dropNonBundled() до регистрации бандла, restrictToBundled() оставляет реестр = бандл + встроенные в docx. Порядок init() после конструктора — инвариант: addPhysicalFont не перезаписывает занятый ключ (иначе системный Calibri ломает em-dash-fallback) |
| 2 | DocxRewritePipeline.STEP → OleObjectNormalizer → WordprocessingMLPackage.load |
Один zip-проход переписывания XML-частей (правила 1–11 — раздел «Нормализаторы: контракт и правила 1–12» в этом файле) + условная OLE-вычистка (правило 12) |
| 3 | pkg.setFontMapper(mapper) |
Привязка шрифтов документа к физическим TTF |
| 3.5 | DrawingPreRenderer.run(pkg, options) |
c:chart/dgm:relIds → PNG 300 dpi → pic:pic (docx2fo.xslt их не умеет) |
| 4 | new FOSettings(pkg) + FopFallbackFonts.declare(foSettings) |
В FOP-конфиг добавляются все бандл-семейства: FOP встраивает только задекларированные |
| 4.25 | LayoutPostRenderer.register(foSettings) |
Кастомный FORenderer: post-FO padding-компенсация таблиц (start-indent += padding-left первой ячейки), внутри — штатный FORendererApacheFOP |
| 4.5 | foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES) |
Стилист — вендорный xslt/docx2fo.xslt (копия docx4j-export-fo + AUDIT-FIX-патчи: w:rPr/w:position→baseline-shift и AUDIT-FIX-2 moveFrom/moveTo/bdo/dir); Templates компилируется один раз — getTemplates кастит значение в Templates |
| 5 | FORendererApacheFOP.getFopFactoryBuilder + getFOUserAgent |
Непустой title → заголовок PDF |
| 6 | Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL) |
XSL-FO → PDF |
| 7 | finally → getFontTablePart().deleteEmbeddedFontTempFiles() |
В docx4j 17.x OpcPackage.close() нет — пакет в памяти |
warmup() — прогрев ядра (шаги 0–7 на минимальном docx)
Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы; замер 2026-11), её платил первый запрос после деплоя. Публичный WordPdfConverter.warmup() прогоняет шаги 0–7 на минимальном docx, собранном в байтах (три zip-части константами, фикстуры не задействованы; алиас Calibri→Carlito греет маппер и embed-подмножество), и греет Java2D/PNG-энкодер (warmRaster() — растер + GlyphFont.draw + ImageIO.write), иначе первый чартный документ платит ещё ~200 мс. Идемпотентен (volatile warmedUp, метод synchronized), никогда не бросает (провал — warn в JUL), артефакты отбрасываются; вызывать на потоке, сериализующем конвертации. Ядро само себя не зовёт: wordpdf-app ставит warmup головой очереди воркеров в конструкторе ConversionService. Прогретый первый конверт ru-plain.docx HTTP-запросом: 0,13 с против 1,74 с (A/B на одной машине, сборки ветки и main).
Валидация входа и подсчёт страниц
Вход валидируется до convertToStream: WordPdfValidator.validate(bytes, options) (размер → подпись: zip PK\x03\x04 или CFB D0 CF 11 E0 → контейнер → страницы). Для .doc страницы считаются по сырым байтам .doc, до конвертации: checkPageCountDoc = max(SummaryInfo PageCount, 1 + разрывы 0x0C − непрерывные межсекционные (sprmSBkc 0/1) + sprmPFPageBreakBefore) (код — DocFile.countPages). Тот же метод — вход приложения. Скан выполняется ровно один раз по сырому входу, до аллокаций docx4j: правила 1–11 число учитываемых разрывов не увеличивают (правило 9 способно только убрать разрыв внутри скрытого рана — счёт по сырому входу остаётся верхней оценкой лимита).
- Страницы в валидаторе =
max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1); explicit = межсекционныеw:sectPrв body +w:br type="page"+pageBreakBefore(включая таблицы иw:sdt). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities;WordPdfValidatorне зависит от docx4j): атрибуты — по локальному имени (attrLocal, не по transitional-URI: иначе в strict-документеw:br type="page"не засчитываются);sectPrвнутриpPrне считает, последнюю body-direct секцию не считает,continuous-секции не считает, в колонтитуках — толькоw:br type="page",pageBreakBefore— только внутриpPrвнеsectPr(truthyval:null|true|1|on). На не-zip молчит — подпись проверяет вызывающий.checkPageCount— один стриминговый проходZipInputStreamбез буферизации частей (хелперnoCloseглушитclose()сканеров): потребление O(одной части) вместо O(суммы XML-частей).
Нормализаторы: контракт и правила 1–12 (детали)
Контракт: byte[] normalize(byte[]) throws IOException; нечего менять → вернуть тот же массив (assertSame в тестах). Одиннадцать rewrite-нормализаторов цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage→TableIndent→NumberingSuffix→Hidden→Ruby→MathFallback; константу STEP (public static final DocxNormalizer) несёт только DocxRewritePipeline (собирает рерайты сам), у OleObjectNormalizer STEP нет — он подключается лямбдой в WordPdfConverter.normalizers(), а вместо normalize(byte[]) у него normalize(byte[], boolean). Правила 1–11 применяет internal/DocxRewritePipeline — один zip-проход: к каждой записи word/*.xml рерайты применяются последовательно (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); до прохода из word/document.xml извлекается полоса набора (TableIndentNormalizer.bandOf, −1 — полосы нет), и word/headerN.xml/footerN.xml дополнительно прогоняются через TableIndentNormalizer.rewritePart с этой полосой, и из word/styles.xml читается множество vanish-стилей (HiddenTextNormalizer.vanishStyles, цепочка w:basedOn) — контекст правила 9; неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. OleObjectNormalizer — второй условный проход (меняет части, а не XML). Индивидуальные normalize() десяти нормализаторов сохранены (контракт юнит-тестов), но WordPdfConverter их не вызывает — его normalizers(options) = DocxRewritePipeline.STEP + лямбда OLE. Порядок правил значим:
StrictOoxmlNormalizer— strict-OOXML → transitional:a:-проценты иw14:fillToRect→ тысячные ×1000, текстwp14:pctWidth/pctHeight; элементыw:start/w:end→w:left/w:right(кромеw:lvl/w:startв numbering.xml); значенияw:val="start"/"end"уw:jcиw:tabправятся всегда (docx4jJustification.setXslFOзнает только left/center/right/both, для ENDfo:text-alignне пишет вовсе —jc="end"рендерился по левому краю; Part 1 §17.3.1.13:jc val="end"— правовыравнивание в LTR, ST_Jc §17.18.44; RTL вне контура — FOP без complex-script). Strict-ность части определяется наличиемhttp://purl.oclc.org(не «transitional-URI в документе» — mixed-документ трактуется по каждой части). Guard сосуществования форм: атрибутw:start/w:endпереименовывается только внутри открывающего тегаw:ind(MS-OI29500 §2.1.174 — псевдонимы left/right; уw:pgNumTypew:start— старт нумерации страниц, легален в transitional, Part 1 §17.13.4 — не трогается) и не переименовывается, если в том же открывающем теге уже естьw:left/w:right(дубль атрибута ломает well-formedness — регрессииindCoexistLeftStartUntouched,indCoexistForms_convertsNotRejected,pgNumTypeStartAttrUntouched); элементыw:start/w:endв strict-части переименовываются глобально, в transitional — только внутриw:tcMar/w:tblCellMarбез одноимённого соседа (maxOccurs=1на left). Ничего не поменялось →rewriteвернулnull→ исходный массив (StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray).DocxOnOffNormalizer—w:val="off"/"on"→"false"/"true"; якорь по тегу, правится только атрибутw:val, текст между тегами не трогается.SymbolFontNormalizer— PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает<w:sym>, правитw:lvlв numbering.xml; 5 карт по 256 слотов (таблицаSymbolMapperиз docx4j 17.x).FieldNormalizer—fldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple(кэш страниц в PDF не попадает); вложенные/битые поля пропускаются.InvisibleCharNormalizer— вырезает изw:tU+0085, U+2028, U+2029, U+200E/200F, U+202A–202E, U+2060, U+FEFF (FOP делает из них переносы/пустые строки, Arimo/Tinos рисуют боксы). U+00A0/U+00AD/U+200B–U+200D не трогает.GlyphCoverageNormalizer— режет раны по покрытию глифов и пишет семейство вw:rFonts, иначе FOP рисует «#». Покрытие —GlyphFont(fontbox, cmap) + BitSet-кэш, не docx4jGlyphCheck(плодит INFO-лог;java.awt.Fontтребовал fontconfig на хосте). Для serif-ран fallback ищется сначала вSERIF_FAMILIES(dejavu serif,tinos,caladea), затем в sans.TableIndentNormalizer— свёрткаw:tblPr/w:jc(center/right) с любым (в т.ч. отсутствующим/нулевым)w:tblIndв абсолютныйw:tblIndс удалениемw:jc(Word: tblInd — сдвиг от поля после центрирования, MS-OI29500 §2.1.155; docx4j при jc≠left игнорирует tblInd буквально — аудит раскладки ECMA-376, матрица B3, а центрированию пишет абсолютный start-indent без вычета cellMar, поверх которого padding-компенсация правила LayoutPostRenderer уводит текст на +padding — свёртка обязательна и при X=0): center → (W−T)/2+X, right → (W−T)+X, W — полоса набора (pgSz − pgMar left/right; у CT_PageMar полейw:start/w:endнет, полоса берётся из сырого document.xml до правила 1; дефолты 11906/1440 — измеренное поведение docx4j, ECMA дефолтов не фиксирует §17.6.11/.13), T — Σ gridCol; пропускает несколько body-levelsectPr,tblIndс явнымw:type≠ dxa (опущенный type — dxa, §17.4.87),tblPrсtblCellSpacingбезtblInd(нет корректной позиции вставки по CT_TblPrBase),tblW pct, нецелые gridCol. Кромеrewrite(document.xml, полоса из собственного sectPr) естьrewritePart(part, xml, band)—word/headerN.xml/footerN.xmlс полосой из document.xml (в частях колонтитуков своего sectPr нет) иbandOf(documentXml)— экстрактор полосы (−1 — полосы нет). Регрессия — WordPdfConverterTest#tableIndentCentered_shiftedLikeWord, #headerTableIndent_centeredInHeader, #tableCenteredNoIndent_shiftedLikeWord.NumberingSuffixNormalizer—w:suff w:val="space"→ дописанный обычный пробел в конце следующегоw:lvlTextтого же уровня (порядок CT_Lvl suff→lvlText, wml.xsd; ST_LevelSuffix Part 1 §17.9.28): docx4j разделитель не эмитит вовсе (дамп n4.fo); уже пробельный lvlText не дублируется; suff=tab — отдельный Class C-остаток (нужна per-item ширина), nothing совпадает с docx4j. Регрессия — WordPdfConverterTest#suffSpace_labelGetsSpace.HiddenTextNormalizer— вырезание скрытых ранов (Part 1 §17.3.2.41): truthyw:vanishв собственномw:rPrранa (обе OnOff-формы; вал опущен — default true; явныйfalse/0/offв ране перекрывает vanish-стиль) илиw:rStyle∈ vanish-стили изword/styles.xml(транзитивно поw:basedOn, капа цепочки 16, цикл — обрыв); ран с защищённым содержимым (fldChar/instrText/footnoteReference/endnoteReference/drawing/pict/object/txbxContent) не трогается — удаление спаренныхbegin…separate…endсломало бы поле. Word скрытое не печатает, стилист docx4jvanishне читает вовсе → без правила скрытое утекало в PDF. Индивидуальныйnormalize()— свой pass styles.xml. Регрессия — WordPdfConverterTest#hiddenText_notPrinted, #hiddenText_directFalseOverridesVanishStyle, юниты — HiddenTextNormalizerTest.RubyNormalizer— разбор руби-разметки (Part 1 §17.3.3.24–.28): снимается обёрткаw:ruby(схемно-валидная транзишнл-разметкаw:r→w:ruby→rubyPr/rt/rubyBase иначе достаёт catch-all-шаблону XSLT, и база теряется молча),w:rubyBaseразворачивается в обычные раны,w:rt/w:rubyPr/w:rubyAlignвырезаются с содержимым (надстрочница — принятая деградация, ruby-разметки в FOP нет; потеря текста хуже потери аннотации). Чинится в байтах, а не в XSLT: схема docx4j 17.3.2 не биндитw:rubyBase/w:rtвw:r— unmarshaller теряет их до стилиста (в отличие отmoveFrom/moveTo/bdo/dir, которых схема знает — тех ловит AUDIT-FIX-2). Регрессия — WordPdfConverterTest#rubyBase_textPrinted, юниты — RubyNormalizerTest.MathFallbackNormalizer— деградация OMML-формул (§22.1) в текст на хостах без fontconfig:m:oMathPara/m:oMath→ обычные раны с конкатенациейm:t(как в штатном фолбэке docx4jXsltFOFunctions.mathText). JEuclid (jeuclid-fop) при первой формуле обращается к AWT-менеджеру шрифтов, которому на Linux нужен fontconfig; без него —InternalError: Fontconfig head is null(контейнерный рантайм проекта без fontconfig — Containerfile). На хосте с fontconfig рерайт не срабатывает (rewrite→null, тот же массив).m:oMathParaсодержитm:oMath, поэтому блок para заменяется первым. Регрессия — WordPdfConverterTest#ommlMath_drawnAsVectors.OleObjectNormalizer— принимает флагerrorOnOle. Два этапа: дешёвый детект по центральному каталогу zip (ZipFile; читаются только[Content_Types].xmlиword/*.xmlдо первого<w:object; не-zip/нет центрального каталога → входной массив — прежняя снисходительность), переупаковка — только при находке. Детект OLE-бинарников — по[Content_Types].xml: тип…oleObjectили ложный+xml-тип у.bin(XML в bin не бывает;printerSettingsне трогается). Удаляются вместе с rels-ссылками (по типу, включаяTargetMode=External) и Override удалённых частей. Элементы<w:object>изword/*.xmlне выбрасываются, а заменяются статичным представлением — картинкой-плейсхолдером (ECMA-376 §15.2.10):w:drawingпереиспользуется дословно,v:imagedata r:id→ inline-DrawingML на ту же image-часть (размер изstylev:shape, иначеw:dxaOrig/w:dyaOrig×635), блоки сw:controlи без плейсхолдера удаляются. OLE-бинарники никогда не читаются. ПриerrorOnOle=trueвместо вычистки —OleFoundException. Лечит оба механизма падения docx4j: JAXB-разбор бинарника под ложным XML-типом («Content is not allowed in prolog» → NPE) и NPEchunkType is nullв VML-сериализацииw:object. Многочастный: публичный член толькоnormalize(byte[], boolean),rewrite-хука нет.
mc-preprocessor.xslt docx4j (в jar docx4j-core) перебивает strict-namespace'ы в transitional и конвертит pt в twips/half-points, но ветку перевода процентов в тысячные для namespace'ных атрибутов содержит с закомментированным <xsl:value-of select="$cleanValue * 1000"/> (для атрибутов без namespace — она активна), а w:start/w:end в w:left/w:right не маппит вовсе. Поэтому собственный рерайт URI ломать нельзя — он сломал бы pt-конверсию preprocessor'а (FOP получил бы «10pt»).