PDF font caching and default directory
Goal: Technical
Developer: Heng Sin Low
Feature Ticket: IDEMPIERE-7212
Version: iDempiere 14
The problem
PDF generation in org.adempiere.pdf.Document had three limitations when using custom fonts:
Document.writePDF(Pageable, OutputStream)created a newDefaultFontMapperon every PDF export and re-scanned the configured font directory each time, slowing down frequent or batch PDF generation.- Custom fonts in
PDF_FONT_DIRwere only added toDefaultFontMapperfor OpenPDF embedding. If those fonts were not also installed in the operating system, Java AWT fell back to default font metrics during report layout. - Administrators had to explicitly configure the
PDF_FONT_DIRSystem Configurator key before custom fonts could be loaded.
What changed
- Cached
DefaultFontMapper:DocumentcachesDefaultFontMapperinstances by resolved font directory path in aCCache(Document_DefaultFontMapper) bound toAD_SysConfig. Repeated PDF exports reuse the cached mapper instead of scanning the directory again. - Default font directory: When
PDF_FONT_DIRis unset or empty, iDempiere automatically uses thefontssubdirectory underIDEMPIERE_HOME(Ini.getAdempiereHome()). If that directory exists, its fonts are loaded without extra configuration. - Custom AWT font registration:
Document.registerCustomAwtFonts()scans the resolved font directory for.ttf,.otf, and.ttcfiles and registers them with Java AWT'sGraphicsEnvironment.ReportEngine.layout()calls this method before creating theLayoutEngineso report layout metrics match the fonts embedded in the PDF. - Cache Reset support: Both font caches (
Document_DefaultFontMapperandDocument_AwtFonts) useAD_SysConfigas their cache table. Running Cache Reset picks up changes toPDF_FONT_DIRor newly added font files without restarting the server.
How to set it up
Use the default font directory
- Create a
fontsdirectory insideIDEMPIERE_HOMEif it does not already exist. - Copy your
.ttf,.otf, or.ttcfont files intoIDEMPIERE_HOME/fonts. - If the server is already running and has generated a PDF or report layout, run the Cache Reset process so iDempiere loads the new fonts.
Use a custom font directory
- Log in with the System Administrator role.
- Open the System Configurator window.
- Search for or create the
PDF_FONT_DIRrecord at the System configuration level. - Set Search Key (
Value) to the full path of your font directory. - Save the record and run Cache Reset if the server is already running.
Configuration
| System Configurator key | Default | Level | What it does |
|---|---|---|---|
PDF_FONT_DIR | Empty (falls back to IDEMPIERE_HOME/fonts) | System | Directory scanned for custom .ttf, .otf, and .ttc font files for AWT registration and PDF embedding. |
Technical notes
org.adempiere.pdf.Document.registerCustomAwtFonts()is a public static method that resolves the font directory fromMSysConfig.getValue(MSysConfig.PDF_FONT_DIR, "")ornew File(Ini.getAdempiereHome().trim(), "fonts").getPath(). It loads.ttf,.otf, and.ttcfiles withFont.createFonts(file)and registers them inGraphicsEnvironment.getLocalGraphicsEnvironment(). Unreadable or invalid font files log a warning without interrupting the remaining files.Documentmaintains twoCCacheinstances backed byMSysConfig.Table_Name:Document_DefaultFontMapper(CCache<String, DefaultFontMapper>): stores oneDefaultFontMapperper resolved directory path.FontFactory.registerDirectories()is invoked once before building the first mapper.Document_AwtFonts(CCache<String, Boolean>): records directory paths whose fonts have already been registered with AWT.
org.compiere.print.ReportEngine.layout()callsDocument.registerCustomAwtFonts()prior to instantiatingLayoutEngine.ServerReportCtlTest.testCustomPdfFontDirectory()covers empty and customPDF_FONT_DIRresolution, invalid font file handling, AWT font registration, PDF font embedding, andCacheMgtreset behavior.
Migration impact
None. Existing PDF_FONT_DIR configurations continue to work as before. Installations with an unset or empty PDF_FONT_DIR now scan IDEMPIERE_HOME/fonts automatically when that directory exists.