Office and PDF Libraries

hsyco.jar includes two libraries for working with documents, that plugins and drivers can use directly, with no extra jar: compile with hsyco.jar in the classpath, as for any plugin.

Library	Version	Modules in hsyco.jar	Files
Apache POI	5.5.1	poi, poi-ooxml, poi-ooxml-lite	Excel .xlsx and .xls, Word .docx, PowerPoint .pptx
Apache PDFBox	3.0.8	pdfbox, fontbox, pdfbox-io	Create, read, merge, split, fill and render PDF files

To create PDF documents with flowing text, tables, images and page numbers, use the PDF Document API, an HSYCO API built on PDFBox. Use PDFBox directly to read, merge, split, fill and render PDF files.

The libraries' API is their own, not part of the HSYCO API: use the library documentation, the POI javadoc and component guides, and the PDFBox 3.0 javadoc. PDFBox 3.0 differs from the 2.0 examples found on the web: see the PDFBox migration guide.

Not included: the legacy .doc, .ppt and Outlook .msg formats (POI poi-scratchpad) and conversion of Office files to PDF.

Java 8

HSYCO must also run on Java 8, so hsyco.jar has the latest versions of these libraries that run on Java 8. POI 5.5.1 is the last POI version for Java 8: POI 6 needs Java 17.

Writing an Excel file

try (SXSSFWorkbook wb = new SXSSFWorkbook(100)) {
	wb.setCompressTempFiles(true);
	Sheet sheet = wb.createSheet("Readings");
	Row row = sheet.createRow(0);
	row.createCell(0).setCellValue("Temperature");
	row.createCell(1).setCellValue(21.5);
	try (OutputStream out = new FileOutputStream("exports/readings.xlsx")) {
		wb.write(out);
	}
}

SXSSFWorkbook keeps only a window of rows in memory and the rest in temporary files under java.io.tmpdir, which it deletes when closed: use it for large exports. Without compression, the temporary files take about 24 MB per 100,000 rows of 5 columns; with setCompressTempFiles(true), about 3 MB. On systems with a small /tmp, set a larger temporary folder with TempFile.setTempFileCreationStrategy(new DefaultTempFileCreationStrategy(new File("exports/tmp"))).

Extracting the text of a PDF file

try (PDDocument pdf = Loader.loadPDF(new File("inbox/invoice.pdf"))) {
	String text = new PDFTextStripper().getText(pdf);
	messageLog("invoice: " + pdf.getNumberOfPages() + " pages, " + text.length() + " characters");
}

To write PDF text that PDFBox's standard fonts don't cover, such as Greek or Cyrillic, load the Liberation Sans font included in PDFBox with PDType0Font.load(doc, PDDocument.class.getResourceAsStream("/org/apache/pdfbox/resources/ttf/LiberationSans-Regular.ttf")).

Notes

• Don't keep your own copy of POI, PDFBox, XMLBeans, commons-compress or Log4j in the HSYCO folder: its classes would mix with those in hsyco.jar and fail at run time with NoSuchMethodError or NoClassDefFoundError. HSYCO writes a warning in the error log at startup for a copy unpacked as class files, such as an org/apache/poi folder, but not for one kept as a JAR file. Remove the copy and recompile your code against hsyco.jar.
• What these libraries log is discarded. Log errors yourself with errorLog().
• Files that come from email or uploads may be damaged or built to exhaust memory. Check their size before opening them, limit the pages or rows you process, and handle IOException. HSYCO runs everything in one Java process, so an OutOfMemoryError caused by one file stops all of HSYCO.
• The first use of POI loads many classes: it takes a few seconds on a Raspberry Pi. Do document work in a separate thread, not in callbacks that must return quickly.
• The libraries need no display. On a server without fonts, check that autoSizeColumn and PDF rendering work before relying on them.