perf(core): WordPdfConverter.warmup() — прогрев ядра минимальным docx

Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы),
её платил первый запрос после деплоя. warmup() прогоняет весь пайплайн на
минимальном docx, собранном в байтах (фикстуры не задействованы), и греет
Java2D/PNG-энкодер для пре-рендера диаграмм. Идемпотентен (volatile флаг),
не бросает (провал — warn в JUL), артефакты отбрасываются. Ядро само себя
не прогревает — момент прогрева решает приложение.

Прогретая первая конвертация ru-plain.docx: 100 мс против ~1,4 с холодную.
This commit is contained in:
Pjandro
2026-11-03 20:23:59 +00:00
parent 33d829a22d
commit 1f00512a66
2 changed files with 119 additions and 0 deletions
@@ -11,6 +11,7 @@ import org.docx4j.convert.out.fo.renderers.FORendererApacheFOP;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import ru.pjandro.wordpdf.fonts.BundledFontMapper;
import ru.pjandro.wordpdf.fonts.BundledFonts;
import ru.pjandro.wordpdf.fonts.GlyphFont;
import ru.pjandro.wordpdf.internal.chart.ChartImageHandler;
import ru.pjandro.wordpdf.internal.chart.DrawingPreRenderer;
import ru.pjandro.wordpdf.internal.DependencyGuard;
@@ -21,13 +22,23 @@ import ru.pjandro.wordpdf.internal.OleObjectNormalizer;
import ru.pjandro.wordpdf.internal.FopFallbackFonts;
import ru.pjandro.wordpdf.internal.LayoutPostRenderer;
import java.awt.Graphics2D;
import java.awt.RenderingHints;
import java.awt.geom.Ellipse2D;
import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import javax.xml.transform.Templates;
import javax.xml.transform.stream.StreamSource;
import javax.imageio.ImageIO;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.logging.Logger;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
/**
* Конвертер docx -> PDF на базе docx4j + Apache FOP
@@ -155,6 +166,106 @@ public final class WordPdfConverter {
return bos.toByteArray();
}
/** Флаг «ядро прогрето»: повторные вызовы {@link #warmup()} — no-op. */
private static volatile boolean warmedUp;
private static final Logger LOG = Logger.getLogger(WordPdfConverter.class.getName());
/**
* Прогрев ядра: первая конвертация после старта JVM стоит 1,3–1,7 с
* (JAXB/XSLT/FOP/классы), её платил первый запрос после деплоя. Прогоняет
* пайплайн на минимальном docx, собранном в байтах (фикстуры тестов не
* задействуются), и греет Java2D/PNG-энкодер для пре-рендера диаграмм.
* Идемпотентен, никогда не бросает (провал — только warn); вызывать нужно
* на том же потоке, на котором сериализованы конвертации (ядро не
* потокобезопасно, см. {@code PhysicalFonts}). Артефакты (PDF, растр)
* отбрасываются. Ядро само {@code warmup()} не вызывает — момент прогрева
* решает вызывающее приложение.
*/
public static synchronized void warmup() {
if (warmedUp) {
return;
}
try {
convert(warmupDocx(), "warmup");
warmRaster();
warmedUp = true;
} catch (Throwable t) {
// Провал прогрева не должен валить старт приложения: в худшем
// случае первый запрос заплатит холодный путь, как платил до
// появления warmup().
LOG.warning("Прогрев ядра не выполнен: " + t);
}
}
/** Минимальный docx прогрева: три обязательные части, собранные в zip. */
private static byte[] warmupDocx() throws IOException {
ByteArrayOutputStream bos = new ByteArrayOutputStream(1 << 10);
try (ZipOutputStream zip = new ZipOutputStream(bos, StandardCharsets.UTF_8)) {
putWarmupEntry(zip, "[Content_Types].xml", WARMUP_CONTENT_TYPES);
putWarmupEntry(zip, "_rels/.rels", WARMUP_ROOT_RELS);
putWarmupEntry(zip, "word/document.xml", WARMUP_DOCUMENT);
}
return bos.toByteArray();
}
private static void putWarmupEntry(ZipOutputStream zip, String name, String xml)
throws IOException {
zip.putNextEntry(new ZipEntry(name));
zip.write(xml.getBytes(StandardCharsets.UTF_8));
zip.closeEntry();
}
/** Маркер {@code wordprocessingml.document} — требование WordPdfValidator. */
private static final String WARMUP_CONTENT_TYPES = """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">\
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>\
<Default Extension="xml" ContentType="application/xml"/>\
<Override PartName="/word/document.xml" \
ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>\
</Types>""";
private static final String WARMUP_ROOT_RELS = """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\
<Relationship Id="rId1" \
Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" \
Target="word/document.xml"/>\
</Relationships>""";
/**
* Текст ранa: алиас Calibri→Carlito прогревает маппер и embed-подмножество
* Carlito; em dash (U+2014) — обычный глиф Carlito, а fallback-путь для
* U+2000–U+2EFF декларируется {@code FopFallbackFonts.declare} на каждом
* конверте и прогревается самим прогоном.
*/
private static final String WARMUP_DOCUMENT = """
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">\
<w:body><w:p><w:r><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri"/></w:rPr>\
<w:t>Warmup text with em dash — for font subsetting.</w:t></w:r></w:p>\
<w:sectPr><w:pgSz w:w="11906" w:h="16838"/>\
<w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440" \
w:header="720" w:footer="720" w:gutter="0"/></w:sectPr></w:body></w:document>""";
/**
* Прогрев Java2D/PNG-энкодера: первый «чартный» документ после старта
* иначе платит ещё ~200 мс холодного растрового пути (пре-рендер
* диаграмм — raster + {@link GlyphFont}). Растер headless-безопасен,
* fontconfig не нужен (глифы — fontbox, см. javadoc {@link GlyphFont}).
*/
private static void warmRaster() throws IOException {
BufferedImage img = new BufferedImage(64, 64, BufferedImage.TYPE_INT_ARGB);
Graphics2D g = img.createGraphics();
g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
g.fill(new Ellipse2D.Double(4, 4, 32, 32));
GlyphFont.of(BundledFonts.FALLBACK_FAMILY, BundledFonts.V_REGULAR)
.draw(g, "Warmup", 2, 30, 12);
g.dispose();
ImageIO.write(img, "png", new ByteArrayOutputStream());
}
/**
* Ядро конвертации: docx -> XSL-FO -> FOP -> PDF в поток. Шаг 0 — проверка
* совместимости commons-compress в classpath потребителя (DependencyGuard):
@@ -533,6 +533,14 @@ class WordPdfConverterTest {
assertTrue(text.contains("quick brown fox"), fixture + ": нет «quick brown fox»: " + text);
}
@Test
void warmup_idempotentAndPipelineIntact() throws Exception {
WordPdfConverter.warmup();
WordPdfConverter.warmup(); // повторный вызов — no-op, не бросает
// прогрев не сломал штатный путь: конвертация прогретым ядром
assertEnglishText("en-plain.docx");
}
@Test
void mixed_headingListTable() throws Exception {
assertHeadingListTable("ru-en-mixed.docx");