How do I use Java libraries (JAR files) from BAW server scripts: server files, class loading, and what to avoid?

Question

We need a Java library (PDF generation, a client SDK) from a server script. Where do the JAR files go so that Packages.* finds them, how are they versioned with the process app, and what breaks on CP4BA?

Answer 1

Process Designer supports server files: add a JAR under Files > Server File in a toolkit; it is packaged into the toolkit's snapshot and put on the classpath of every process app that depends on the toolkit - no server configuration, no restart, versioned with the snapshot. Server scripts then use Packages.<package>.<Class> (Rhino):

// toolkit "PDF Toolkit": server file pdfbox-2.0.30.jar (plus its dependencies fontbox-2.0.30.jar, commons-logging-1.2.jar)
var doc = new Packages.org.apache.pdfbox.pdmodel.PDDocument();
var page = new Packages.org.apache.pdfbox.pdmodel.PDPage(); doc.addPage(page);
var cs = new Packages.org.apache.pdfbox.pdmodel.PDPageContentStream(doc, page);
cs.beginText(); cs.setFont(Packages.org.apache.pdfbox.pdmodel.font.PDType1Font.HELVETICA, 12); cs.newLineAtOffset(50, 750);
cs.showText("Order " + tw.local.order.number); cs.endText(); cs.close();
var out = new Packages.java.io.ByteArrayOutputStream(); doc.save(out); doc.close();
tw.local.pdfBase64 = String(Packages.java.util.Base64.getEncoder().encodeToString(out.toByteArray()));

Rules and pitfalls:

• Class loading: server files are loaded by a per-snapshot class loader; two toolkits providing different versions of the same library in one app cause "wrong version" errors (NoSuchMethodError) - keep one library toolkit. Libraries that the platform already ships (Jackson, Apache HTTP client, WebSphere / Liberty JAX-RS) may win over yours - prefer the platform's version or use a library without conflicting transitive dependencies.
• Static state and threads: never start threads or keep static caches with instance data in a library used from scripts; services run in many threads and snapshots reload.
• Size: every server file is stored in the repository and shipped in the twx; keep JARs small (no fat jars with 50 MB of dependencies).
• Security: the JAR runs with the server's permissions; review third-party code, and forbid System.exit or file system writes outside the temp directory.
• CP4BA: the same mechanism works (the JAR ships with the snapshot); JVM-level additions (jvm.options, shared libraries in the image) are not available - everything must be a server file. Native libraries (JNI) are not supported.
• Alternative: put heavy logic in a separate microservice (REST) called from a service flow - easier to test, scale and upgrade than a library inside the engine.

References

• BAW documentation - managing server files and external files in process applications
• JavaScript API (Rhino) and Java access from scripts