Java 8 vs. 11 compatibility

[kriegaex]

Hello.

I am using this module as a part of my Maven site generator for a Maven plugin. Everything works fine on Java 8, but there is a PlantUML diagram embedded somewhere in my asciidocs, and because of this error (added extra line breaks), the diagram is not created.

Failed to generate image:
  cannot link Java class org.asciidoctor.diagram.CommandProcessor
  org/asciidoctor/diagram/CommandProcessor has been compiled by a more recent version
  of the Java Runtime (class file version 55.0), this version of the Java Runtime only
  recognizes class file versions up to 52.0

It would be regrettable to require Java 11 for my plugin because of a single image. Is there a specific reason for requiring Java 11 as a build target? Commit aae065a2 did not explain anything about it. Are you using a lot of Java 9+ language features unavailable in Java 8, or are you depending on something that does? Otherwise, would it be possible to downgrade to target 8 again?

---

Update: I just found https://github.com/asciidoctor/asciidoctorj-diagram/issues/39, which is about the same topic. But before you just close it as "expected behaviour", can someone please explain what this exactly means?

This requirement comes from asciidoctor-diagram itself.

@robertpanzer, you wrote that over there, maybe you can enlighten me.

[kriegaex]

I am also having a hard time figuring out in which Maven plugin dependency to find class CommandProcessor. I cannot find the class anywhere on Maven Central, and the only diagram-specific dependency in my POM is asciidoctorj-diagram, which only contains Ruby stuff. So, I do not even know where to start looking for this class and how to downgrade anything.

[pepijnve]

asciidoctor-diagram itself is a Ruby gem. When it needs to call out to Java based diagram tools, it does so indirectly. Rather than launching the tools directly, that work is delegated to a Java subprocess that then runs the Java code for the tool in question. The rationale behind this setup is that it avoids the JVM startup cost per diagram. Instead a single subprocess is spawned and kept alive for the duration of the asciidoctor run.

asciidoctorj-diagram is a special case. Since the code is already running in a JVM thanks to JRuby there's no need to spawn an additional process. Instead the same code that normally runs in the subprocess is called directly in process.

Because this gem is a Ruby gem in the first place and, as far as I know, there's no way for a Ruby gem to pull in a maven dependency them Java glue code is embedded in the gem as a jar file. That's located right here https://github.com/asciidoctor/asciidoctor-diagram/blob/master/lib/asciidoctor-diagram/util/server-2.0.0.jar. That server uses ServiceLoader to find tool integrations. For each tool there's a separate integration jar as well. For PlantUML for instance that's located at https://github.com/asciidoctor/asciidoctor-diagram/blob/master/lib/asciidoctor-diagram/plantuml/plantuml-2.0.7.jar

[kriegaex]

Oh, you are committing JARs directly into the Git repository. OK, I downloaded those two JARs, but they only contain Java 8 class files, I checked with javap. So for me, the missing part of this jigsaw puzzle still is where the Java 11 requirement comes from. Is it really necessary? Are you using any dependency that contains Java 11 files?

[kriegaex]

OK, I understand. I downloaded the latest version 2.1.0, which is Java 8. Version 2.0.7 was Java 11. You were just too fast for me and committed a Java 8 compatibility fix while we were talking.

[pepijnve]

That's just the way gradle was configured. I reverted to 1.8 as source/target compatibility. Only one issue popped up which was usage of a Java 9 exception class in a catch clause in the Structurizr integration. After removing that things compile fine. Most of the tools that are called out to are likely to require more recent Java versions though. I'll catalog the version requirements and add that to the documentation pages.

[kriegaex]

Splendid! Please let me know which dependency to watch here or on Maven Central for a new release. Then, I can re-test and provide feedback. Would it be something like org.asciidoctor:asciidoctorj-diagram:2.2.15?

[pepijnve]

I'm going for 2.3.0. Should have done that with the actual breaking change to Java 11 😄 I'll make the Ruby gem release when CI gives the green light. Releasing the j variant is up to @robertpanzer.

[kriegaex]

Sorry for the late feedback, but I was not notified about the "j" variant's 2.3.0 release, I just noticed now by chance. I upgraded and can confirm that my PlantUML diagram is now generated as expected on JDK 8. Thanks, @pepijnve and @robertpanzer.