perf(core): общая FopFactory на JVM со сбросом имиджевых кешей
PR checks / web (pull_request) Successful in 39s
PR checks / java (pull_request) Successful in 1m31s

Переиспользование FopFactory между конвертациями раньше запрещалось:
форк FOP копит на фабрике image-кеши (xmlgraphics-commons ImageCache:
imageInfos/images и ImageObjectCacheImpl), ключи записей — временные
файлы file:/tmp/<uuid>… с уникальным на конвертацию именем, попадания
не бывает никогда, а soft-ссылки не освобождаются при свободной куче
(2 ГБ фиксированная): после 30 конвертаций ~1,5 ГБ живых byte[]
против 17 МБ, рост live-кучи, Full GC.

Теперь фабрика одна на JVM, а каждая конвертация в finally вызывает
resetSharedImageCaches() — публичные clearCache() у ImageCache и
ImageObjectCacheImpl. Разбор шрифтов форка (GPOS, ~140k объектов)
теперь один раз на JVM. Замер после фикса: 16,8 МБ живых byte[],
heap used 89 МБ после 30 конвертаций, Full GC от нагрузки — 0.

Регрессии — WordPdfConverterTest#fopFactorySharedAcrossConversions,
#sharedImageCaches_clearedAfterConversion.
This commit is contained in:
Pjandro
2026-11-08 14:06:23 +00:00
parent 8061a2fbe7
commit bc98a12421
2 changed files with 107 additions and 9 deletions
@@ -2,6 +2,8 @@ package ru.pjandro.wordpdf;
import org.apache.fop.apps.FOUserAgent;
import org.apache.fop.apps.FopFactory;
import org.apache.fop.util.ImageObjectCache;
import org.apache.fop.util.ImageObjectCacheImpl;
import org.docx4j.Docx4J;
import org.docx4j.XmlUtils;
import org.docx4j.Docx4jProperties;
@@ -82,6 +84,57 @@ public final class WordPdfConverter {
private WordPdfConverter() {
}
private static volatile FopFactory sharedFopFactory;
/**
* FopFactory, общая на JVM: разбор шрифтов форка (GPOS-таблицы, ~140k
* объектов) выполняется один раз, а не на каждую конвертацию. Фабрика
* хранит имиджевые кеши ({@code ImageManager#getCache()} и
* {@link ImageObjectCacheImpl}) c ключами {@code file:/tmp/<uuid>…} —
* уникальными на каждую конвертацию (docx4j выкладывает медиа во временные
* файлы), поэтому кеш никогда не попадает и растёт на декодированный растр
* каждого изображения (замер 2026-11: ~1,5 ГБ живых byte[] после 30
* конвертаций с картинками). Поэтому каждая конвертация обязана вызвать
* {@link #resetSharedImageCaches()} в finally.
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
*/
static FopFactory sharedFopFactory(final FOSettings foSettings) {
FopFactory factory = sharedFopFactory;
if (factory == null) {
synchronized (WordPdfConverter.class) {
if (sharedFopFactory == null) {
try {
sharedFopFactory = FORendererApacheFOP.getFopFactoryBuilder(foSettings).build();
} catch (org.apache.fop.apps.FOPException e) {
throw new ConversionException("Не удалось собрать FOP-фабрику", e);
}
}
factory = sharedFopFactory;
}
}
return factory;
}
/**
* Сброс имиджевых кешей общей фабрики после конвертации. Без него форк
* удерживает растр каждого изображения документа до конца жизни JVM:
* записи лежат в soft-ссылках, которые сборщик не трогает, пока свободная
* куча велика (куча стенда фиксирована 2 ГБ). Сбросы публичные:
* {@code ImageCache.clearCache()} и {@code ImageObjectCacheImpl.clearCache()}.
* Регрессия — WordPdfConverterTest#sharedImageCaches_clearedAfterConversion.
*/
static void resetSharedImageCaches() {
FopFactory factory = sharedFopFactory;
if (factory == null) {
return;
}
factory.getImageManager().getCache().clearCache();
ImageObjectCache imageObjects = factory.getImageObjectCache();
if (imageObjects instanceof ImageObjectCacheImpl impl) {
impl.clearCache();
}
}
/**
* Конвертирует байты .docx (или бинарного .doc Word 97–2003 — формат
* определяется по сигнатуре байтов) в PDF. Работа с файлами — забота
@@ -329,14 +382,10 @@ public final class WordPdfConverter {
// используется.
foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES);
// 5. Метаданные PDF: заголовок — из параметра title. Фабрика
// ОБЯЗАНА собираться на каждую конвертацию: переиспользование
// одной FopFactory между прогонами (put в settings под
// FOP_FACTORY, docx4j это поддерживает) копит шрифтовые данные
// форка FOP на каждый render — замер 2026-11: после 30
// конвертаций ~1,4 ГБ живых byte[] против 17 МБ при per-conversion
// сборке, рост live-кучи и Full GC.
FopFactory fopFactory = FORendererApacheFOP.getFopFactoryBuilder(foSettings).build();
// 5. Метаданные PDF: заголовок — из параметра title. Фабрика —
// общая на JVM (см. sharedFopFactory); после конвертации её
// имиджевые кеши обязаны быть сброшены (шаг 7).
FopFactory fopFactory = sharedFopFactory(foSettings);
FOUserAgent foUserAgent = FORendererApacheFOP.getFOUserAgent(foSettings, fopFactory);
if (title != null && !title.isEmpty()) {
foUserAgent.setTitle(title);
@@ -345,11 +394,14 @@ public final class WordPdfConverter {
// 6. Проход XSLT (медленнее, но полнее), вывод в поток
Docx4J.toFO(foSettings, os, Docx4J.FLAG_EXPORT_PREFER_XSL);
} finally {
// 7. Уборка временных файлов встроенных в docx шрифтов
// 7. Уборка временных файлов встроенных в docx шрифтов и сброс
// имиджевых кешей общей FopFactory (без него форк копит растр
// каждого изображения: ~1,5 ГБ на 30 конвертаций, 2026-11).
if (pkg.getMainDocumentPart() != null
&& pkg.getMainDocumentPart().getFontTablePart() != null) {
pkg.getMainDocumentPart().getFontTablePart().deleteEmbeddedFontTempFiles();
}
resetSharedImageCaches();
// Примечание: в docx4j 11.x OpcPackage.close() отсутствует —
// пакет загружается в память и ничего не закрывает.
}
@@ -1,5 +1,6 @@
package ru.pjandro.wordpdf;
import org.apache.fop.apps.FopFactory;
import org.apache.pdfbox.Loader;
import org.apache.pdfbox.cos.COSBase;
import org.apache.pdfbox.cos.COSName;
@@ -2746,4 +2747,49 @@ class WordPdfConverterTest {
}
}
/**
* Повторная конвертация обязана переиспользовать ту же FopFactory: разбор
* шрифтов форка дорог (GPOS-таблицы, ~140k объектов) и на общей фабрике
* выполняется один раз на JVM.
*/
@Test
void fopFactorySharedAcrossConversions() throws Exception {
WordPdfConverter.convert(sampleBytes("ru-plain.docx"), "ru-plain");
FopFactory first = WordPdfConverter.sharedFopFactory(null);
WordPdfConverter.convert(sampleBytes("en-plain.docx"), "en-plain");
assertSame(first, WordPdfConverter.sharedFopFactory(null),
"повторная конвертация обязана переиспользовать ту же FopFactory");
}
/**
* После конвертации фабричные image-кеши FOP обязаны быть пусты: ключи
* записей ({@code file:/tmp/<uuid>…}) уникальны на каждую конвертацию,
* попаданий не бывает никогда, а непустой кеш — утечка декодированного
* растра до конца жизни JVM (замер 2026-11: ~1,5 ГБ живых byte[] после
* 30 конвертаций). Регрессия — этот тест, фикстура samples/chart-types.docx.
*/
@Test
void sharedImageCaches_clearedAfterConversion() throws Exception {
WordPdfConverter.convert(sampleBytes("chart-types.docx"), "chart-types");
FopFactory factory = WordPdfConverter.sharedFopFactory(null);
Object imageCache = factory.getImageManager().getCache();
assertEquals(0, softMapSize(imageCache, "imageInfos"),
"ImageCache.imageInfos обязан быть пуст после конвертации");
assertEquals(0, softMapSize(imageCache, "images"),
"ImageCache.images обязан быть пуст после конвертации");
assertEquals(0, softMapSize(factory.getImageObjectCache(), "cache"),
"ImageObjectCacheImpl обязан быть пуст после конвертации");
}
/** Размер внутренней {@code map} SoftMapCache (package-private поле). */
private static int softMapSize(Object cacheHolder, String field) throws Exception {
java.lang.reflect.Field f = cacheHolder.getClass().getDeclaredField(field);
f.setAccessible(true);
Object softCache = f.get(cacheHolder);
java.lang.reflect.Field m = softCache.getClass().getDeclaredField("map");
m.setAccessible(true);
return ((Map<?, ?>) m.get(softCache)).size();
}
}