How to run DITA-OT within a JAR packaged using Maven?

[karlfranks]

I have added the org.dita-ot.dost dependency from Maven Central, and also manually ran mvn:install to install dost-configuration.jar from the DITA-OT download as this JAR isn't included.

Then added DITA-OT 3.7.3 as a resource (excluding the lib directory) and attempting to make use of it through the Java API.

The issue is you need to supply a File pointing to the DITA-OT directory (https://javadoc.io/doc/org.dita-ot/dost/latest/org/dita/dost/ProcessorFactory.html), was attempting to use this code to access it via a resource path:

File ditaOtDir = new File(this.getClass().getResource("/dita-ot-3.7.3").toURI());

However when I call ProcessorFactory pf = ProcessorFactory.newInstance(ditaOtDir); this causes Exception in thread "main" java.lang.IllegalArgumentException: DITA-OT directory must be absolute at org.dita.dost.ProcessorFactory.newInstance(ProcessorFactory.java:30) ...

Also attempted to construct the File in a different way, to little success as it causes a different error when calling run on the Processor:

URL ditaOtDirUrl = this.getClass().getResource("/dita-ot-3.7.3");
File ditaOtDir = new File(ditaOtDirUrl.toString()).getAbsoluteFile();

Caused by: Basedir /full/example/path/jar:file:/path/to/this.jar!/dita-ot-3.7.3 does not exist 
at org.apache.tools.ant.Project.setBaseDit(Project.java:858)
 at org.dita.dost.Processor.run(Processor.java:207)
...

Am I missing something obvious about how to construct this File object or is it just not possible to package our JAR like this with DITA-OT included within it?

[raducoravu]

@karlfranks the org.dita-ot.dost Maven project is useful just to compile Java extensions.
The DITA OT is a big folder containing startup scripts, Java JAR libraries, XSLT stylesheets, it cannot be packed in a JAR file as it is not 100% Java code.
I would recommend running the DITA OT as an external Java process using the "bin/dita" executable scripts with the appropriate parameters.

[karlfranks]

I understand it's a bundle of various code projects, but that seems in complete contradiction to what the DITA-OT website states about the Java API - "DITA Open Toolkit includes a Java Application Programming Interface to allow developers to embed the toolkit more easily into other Java programs. When using the API, programmers don’t need to know or care that DITA-OT uses Ant, they can just use Java." https://www.dita-ot.org/dev/reference/java-api.html

We wanted to bundle everything together into one JAR to make it simpler for end-users and I was just checking if there was something I'd missed about how to call it, but we're currently leaning to keeping the DITA-OT directory outside of the JAR because of how it checks for absolute file paths.

[jelovirt]

You can run DITA-OT using the Java API but you have to set up the environment so that the DITA-OT distribution is expanded into a directory, not in a JAR. In your case the error message

Caused by: Basedir /full/example/path/jar:file:/path/to/this.jar!/dita-ot-3.7.3 does not exist

Shows that the URL returned from classloader gives you back a JAR URI and that doesn't work.

[raducoravu]

@jelovirt @infotexture in my opinion the API topic should be removed completely: https://www.dita-ot.org/dev/reference/java-api.html
because it seems to give the wrong impression that you could pack and use the entire DITA OT from a JAR.

[jelovirt]

@raducoravu IMO we should not remove the API topic if we have an API. Instead we should add a note that DITA-OT cannot be run from a JAR and requires the distribution package to be extracted to a directory.

[jelovirt]

@raducoravu @infotexture Rereading https://www.dita-ot.org/dev/reference/java-api.html and I think we need to split this topic into two.

1. Using the Java API — this should not mention the JAR in Maven at all, because it's not what's needed. What you do need is a full DITA-OT distribution, extracted to a directory, and then all JAR files + config directory added classpath.
2. Developing plug-ins with Java components — this content could be used extends https://www.dita-ot.org/dev/topics/plugin-javalib.html or then add another plug-in example topic that shows how to add custom Java code. This topic would then mention the JAR in Maven.