The asciidoctor-java-integration is the official means of using Asciidoctor to render all your AsciiDoc documentation using Java instead of Ruby.
Since asciidoctor-java-integration is a standard jar file, the only thing you should do is add library into classpath.
...
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-java-integration</artifactId>
<version>${asciidoctor.version}</version> (1)
...
</dependency>
</dependencies>
......
dependencies {
compile('org.asciidoctor:asciidoctor-java-integration:${asciidoctor.version}') { (1)
transitive = false
}
}
...-
As this library tracks the version of asciidoctor, you can use which every version of asciidoctor you prefer.
The core interface of asciidoctor-java-integration is Asciidoctor interface. It provides two methods for rendering asciidoc content, render and renderFile. Both of them returns a string with rendered content.
| Name | Description |
|---|---|
|
Parse the AsciiDoc content into a Document and render it to the specified backend format. |
|
Parse the content of AsciiDoc file into a Document and render it to the specified backend format. |
Also a factory method is provided to create an instance of Asciidoctor interface.
import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
...
Asciidoctor asciidoctor = create();
...And then we can call render methods depending on our requirements.
...
String rendered = asciidoctor.render("*This* is it.", Collections.EMPTY_MAP);
System.out.println(rendered);
...But also you can render the content of a file.
...
String rendered = asciidoctor.renderFile(new File("target/test-classes/rendersample.asciidoc"), Collections.EMPTY_MAP);
System.out.println(rendered);
...Another method provided by Asciidoctor interface is renderDirectory. This method renders all AsciiDoc files (.asc,+ .asciidoc+,+ .ad+ or .adoc), that are present inside provided folder or any of its subfolder.
In case rendered content is not written in files, this method returns an array with all documents rendered.
...
String[] allRenderedFiles = asciidoctor.renderDirectory(new File("target/test-classes/src"), new HashMap<String, Object>());
for(String renderedFile:allRenderedFiles) {
System.out.println(renderedFile);
}
...Another way to render AsciiDoc content is by calling render method but providing a Reader and Writer. Reader interface is used as source, and rendered content is written through Writer interface.
...
FileReader inputAsciidoctorFile = new FileReader(new File("target/test-classes/rendersample.asciidoc"));
StringWriter rendererWriter = new StringWriter();
asciidoctor.render(inputAsciidoctorFile, rendererWriter, options().asMap());
StringBuffer renderedContent = rendererWriter.getBuffer();
assertRenderedFile(renderedContent.toString());
...Asciidoctor supports different kind of options, like in_place which renders the output inside a file, template_dir used to provide a directory of Tilt-compatible templates to be used instead of the default built-in templates, or for example attributes option where we can set key-value pairs of attributes that will be used within asciidoc document.
The second parameter of render methods are a java.util.Map where we can set all these options.
Map<String, Object> attributes = new HashMap<String, Object>();
attributes.put("backend", "docbook");
Map<String, Object> options = new HashMap<String, Object>();
options.put("in_place", true);
options.put("attributes", attributes);
String render = asciidoctor.renderFile("target/test-classes/rendersample.asciidoc", options);See that in previous example we have created a Map, where we have put the options and attributes (creating a Map too) required to render input as docbook and generate an output file.
But asciidoctor-java-integration also provides two builder classes to create these maps in a more readable form.
AttributesBuilder is provided for creating a map with required attributes set, and OptionsBuilder can be used for options. Previous example but using these classes looks like:
import static org.asciidoctor.AttributesBuilder.attributes;
import static org.asciidoctor.OptionsBuilder.options;
...
Map<String, Object> attributes = attributes().backend("docbook").asMap();
Map<String, Object> options = options().inPlace(true).attributes(attributes).asMap();
String render = asciidoctor.renderFile("target/test-classes/rendersample.asciidoc", options);
...A utility class for searching all asciidoc files present in a root folder and all its subfolders is given. In fact it finds all files that end up with .asc, .asciidoc, .ad or .adoc. This class is AsciiDocDirectoryWalker.
DirectoryWalker directoryWalker = new AsciiDocDirectoryWalker("target/test-classes/src");
List<File> asciidocFiles = directoryWalker.scan();Sometimes JRuby starting time is slower than we would expect if we were using standard C-based, non-optimizing standard Ruby. For improving this time, JRuby offers some flags which can be used to tune JRuby applications. Apart of these flags, or in conjunction with them, we can use some java flags to improve even more the startup time.
For small tasks such as converting an AsciiDoc document, there are two JRuby flags can improve the startup time:
| Flag | Value |
|---|---|
|
RUBY1_9 |
|
OFF |
Both flags are set by default inside asciidoctor-java-integration project, so we do not have to worry about setting them manually.
As mentioned before, there are some java flags that can also be used for this purpose. These flags depends on version of JDK and also if you are working on 32/64 bits version. These flags can be set by using JRUBY_OPTS environment variable. Let’s see a summary of these flags and in which versions can be used.
Flag |
JDK |
|
32 bits Java |
|
32/64 bits Java |
|
32/64 bits Java SE 7 |
|
32/64 bits Java SE 7 |
export JRUBY_OPTS="-J-Xverify:none -J-client"Note that you should add -J before the flag.
You can find a full explanation on how to improve startup time of JRuby applications at {https://github.com/jruby/jruby/wiki/Improving-startup-time}[Improving Startup Time]