Apache PDFBox Documentation

To build PDFBox, you must have Java 11 (or higher) and Maven 3 installed. The default build process compiles the Java sources and packages the binary classes into jar packages.

mvn clean install

You can use async-profiler to profile benchmarks. You must provide the path to the libasyncProfiler.so library.

• Basic profiling: Use -prof async:libPath=<path>.
• Flame graph output: Use -prof async:libPath=<path>\;output=flamegraph (note the escaped semicolon).
• Help: Use -prof async:help to see available options.

To build XmpBox, you need Java 6 or higher and Maven 2. The default build compiles Java sources and packages the binary classes into a JAR package.

mvn clean install

To build FontBox from source, you must have Java 6 or higher and Maven installed. The default build process compiles the Java source code and packages the binary classes into a JAR file.

mvn clean install

To run the Rendering.renderGhentCMYK benchmark, you must manually prepare the test PDF files because the Ghent PDF Output Suite V50 requires a license agreement.

1. Download the suite from the Ghent PDF Output Suite V50 download page.
2. Unpack the ZIP file into the target/pdfs directory so that the Ghent_PDF_Output_Suite_V50_Full directory is at the root of that path.
3. Retain only the following file: Ghent_PDF_Output_Suite_V50_Full/Categories/1-CMYK/Test pages/Ghent_PDF-Output-Test-V50_CMYK_X4.pdf.

To measure memory allocation rates, use the -prof gc profiler. When profiling, focus on the norm metric, which measures allocations per operation rather than allocations per second, providing a more stable measurement regardless of code execution speed.

java -jar target/benchmarks.jar -prof gc

The benchmark module uses JMH (Java Microbenchmark Harness). After building the project, you can run benchmarks using the target/benchmarks.jar file.

• Run all benchmarks: java -jar target/benchmarks.jar
• List all available benchmarks: java -jar target/benchmarks.jar -l
• Select specific benchmarks by pattern: java -jar target/benchmarks.jar <PatternOrName> (e.g., LoadAndSave.loadMediumFile)
• List benchmarks matching a pattern: java -jar target/benchmarks.jar -l <Pattern>
• Run a specific test with custom configuration: Use -f (forks), -i (iterations), and -wi (warm-up iterations).

The Apache PDFBox Debugger App can be packaged for distribution on Windows, Linux, and macOS using packr.

Note: The Apache PDFBox project does not provide official support for creating these packages; this information is provided as a guide for interested developers.

Text Extraction Issues

• Meaningless character strings (e.g., "G38G43G36G51G5"): This occurs when characters use a meaningless internal encoding for embedded glyphs. In these cases, text extraction via standard methods may fail, and OCR (Optical Character Recognition) may be required.
• Incorrect character order: PDF text is stored in chunks that may not follow visual order. If text appears in the wrong order, ensure you have enabled sorting in your extraction process.

Classpath and Font Errors

• java.io.IOException: Can't handle font width: This error often indicates that the org/apache/pdfbox/resources directory is missing from your classpath. Ensure you have included the apache-pdfbox-x.x.x.jar in your classpath to resolve this.

Commonly used flags and profiler commands for the PDFBox benchmark JAR:

CLI Flags

• -l: List available benchmarks.
• -lprof: List available profilers.
• -f <int>: Number of forks.
• -i <int>: Number of iterations.
• -wi <int>: Number of warm-up iterations.
• -prof <profiler>: Specify a profiler (e.g., gc or async).