FlexDoc/XML - DiagramKit - FAQ - Generator Setups

This section describes all primary settings that are required (or may be needed) to setup and run the DiagramKit. Once you know those settings, you will be able to configure the FlexDoc/XML+DiagramKit documentation generator for any particular environment you need.

It also provides full examples of how to configure FlexDoc/XML+DiagramKit for some important cases.

How to setup DiagramKit Plugin?

DiagramKit is one of the diagramming plugins of FlexDoc/XML, which means it is a Java-service implementation of Element Image Provider. That is a separate Java module packed in the jar-file:
{flexdoc-xml}/lib/flexdoc-xml-diagramkit.jar
where {flexdoc-xml} is FlexDoc/XML installation directory.

In order to run FlexDoc/XML+DiagramKit, the following settings must be provided on the Java command line running FlexDoc/XML (generator or template designer):

  1. The pathname of flexdoc-xml-diagramkit.jar must be included in Java module/class path.
  2. The JavaFX modules, on which DiagramKit depends also must be found on the Java module/class path:

    When Java is run in non-modular mode (which is the case for Maven), the file path to JavaFX modules can be specified directly to DiagramKit using -m:IMAGE_PROVIDER_CLASSPATH option. In the case of modular mode, it is impossible because Java strictly checks the presence of all required modules before running anything.

  3. The plugin service name must be specified on the Java command line using -m option as follows:

    -m:IMAGE_PROVIDER=DiagramKit

Running with Windows Batch File

Suppose, you want to generate a framed HTML documentation (with OxygenXML diagrams) using XSDDoc | Templates | FramedDoc.tpl template by the XML schema located at the URL: http://www.w3.org/2001/XMLSchema.xsd.

Here is a simple Windows batch file that would launch such a generation (with the red are highlighted settings related to the DiagramKit):

xsddoc.bat – in case of using FlexDoc JRE

:: FlexDoc/XML home directory
set FDH=C:\flexdoc-xml

:: command to invoke JVM (i.e. FlexDoc JRE)
set JAVA=%FDH%\jre\bin\java

:: FlexDoc/XML module path
set MODULE_PATH=%FDH%\lib\flexdoc-xml.jar;%FDH%\lib\flexdoc-xml-diagramkit.jar;%FDH%\lib\xercesImpl.jar

%JAVA%  -Xmx1024m --module-path "%MODULE_PATH%" --module flexdoc.xml/xyz.flexdoc.xml.Generator
-m:IMAGE_PROVIDER=DiagramKit
-template %FDH%\templates\XSDDoc\FramedDoc.tpl
-format HTML -d %FDH%\out -nodialog -launchviewer=false
http://www.w3.org/2001/XMLSchema.xsd

xsddoc.bat – in case of using JavaFX SDK

:: FlexDoc/XML home directory
set FDH=C:\flexdoc-xml

:: the location of JavaFX SDK 'lib' directory
set PATH_TO_FX=C:\javafx-sdk-17\lib

:: FlexDoc/XML module path
set MODULE_PATH=%FDH%\lib\flexdoc-xml.jar;%FDH%\lib\flexdoc-xml-diagramkit.jar;%PATH_TO_FX%;%FDH%\lib\xercesImpl.jar

%JAVA%  -Xmx1024m --module-path "%MODULE_PATH%" --module flexdoc.xml/xyz.flexdoc.xml.Generator
-m:IMAGE_PROVIDER=DiagramKit
-template %FDH%\templates\XSDDoc\FramedDoc.tpl
-format HTML -d %FDH%\out -nodialog -launchviewer=false
http://www.w3.org/2001/XMLSchema.xsd

Running with Apache Ant

You can easily integrate FlexDoc/XML+DiagramKit with the Apache Ant automated build system.

As an example, here is an ANT build.xml file doing the same as the Windows batch file described above.

build.xml

<?xml version="1.0"?>
<project basedir="." name="FlexDoc/XML+DiagramKit Demo">
<!-- This will generate an XML schema documentation -->
<target name="XSDDoc">
<!-- FlexDoc/XML home directory -->
<property name="FDH" value="C:\flexdoc-xml"/>
<!-- FlexDoc/XML Java module path -->
<property name="MP" value="${FDH}\lib\flexdoc-xml.jar;${FDH}\lib\flexdoc-xml-diagramkit.jar;${FDH}\lib\xercesImpl.jar"/>
<!-- The location of FlexDoc JRE -->
<property name="JRE_HOME" value="${FDH}\jre"/>
<!--
Execute FlexDoc/XML generator.
The 'fork' attribute forces Ant to launch the separate JVM for this task.
The 'jvm' attribute sets the command to invoke the JVM (i.e. FlexDoc JRE).
The 'maxmemory' attribute sets the maximum heap size available to JVM when running FlexDoc/XML.
-->
<java modulepath="${MP}" module="flexdoc.xml" classname="xyz.flexdoc.xml.Generator" fork="true" jvm="${JRE_HOME}\bin\java" maxmemory="2048m">
<!--
All options you want to pass to the FlexDoc/XML Generator should be specified
here with the <arg> elements in the same order as on the command line.
-->
<!-- specify DiagramKit as Element Image Provider -->
<arg value="-m:IMAGE_PROVIDER=DiagramKit"/>
<!-- specify the main template -->
<arg value="-template"/>
<arg value="${FDH}\templates\XSDDoc\FramedDoc.tpl"/>
<!-- pass the template parameter 'docTitle' (the documentation title) -->
<arg value="-p:docTitle"/>
<arg value="XML Schema for XML Schemas"/>
<!-- the output format -->
<arg value="-format"/>
<arg value="HTML"/>
<!-- the output directory -->
<arg value="-d"/>
<arg value="${FDH}\out"/>
<!-- do not launch the generator GUI -->
<arg value="-nodialog"/>
<!-- do not launch the default viewer for the output file -->
<arg value="-launchviewer=false"/>
<!--
Specify one or many data source XML files to be processed by the specified template.
Both local pathnames and URLs are allowed.
In this example, it is an XML schema to be documented.
-->
<arg value="http://www.w3.org/2001/XMLSchema.xsd"/>
</java>
</target>
</project>

To run that build.xml file, you can use a Windows batch file specified like the following: 

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\Program Files\Java\jdk-17
call %ANT_HOME%\bin\ant.bat xsddoc

Note that it should be started from the directory containing the Ant build.xml file.

Running with Apache Maven

How to run FlexDoc/XML with Maven is basically explained on this page: FlexDoc/XML | Integrations | Apache Maven. However, linking DiagramKit to this is not straightforward because it requires JavaFX – its modules must be found on the Java module/class path.

On the other hand, since any Maven plugin runs in the same Java thread as Maven itself, FlexDoc JRE cannot be used with it because in order to run Maven the full JDK may be needed. So, to run DiagramKit with Maven, only two possibilities are available:

  1. Using JavaFX Maven plugins – the default Maven distribution of JavaFX (which exists indeed).
  2. Using JavaFX SDK – installed separately

Using JavaFX Maven plugins

Although that possibility seems to be obvious and, in fact, is the default one, there is some problem with it. Currently, all available JavaFX Maven plugins cannot be installed straightforward because of some Maven error happening during the installation:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-plugin-plugin:3.2:descriptor (default-descriptor) on project plugin-with-diagramkit: Execution default-descriptor of goal org.apache.maven.plugins:maven-plugin-plugin:3.2:descriptor failed: Index 18433 out of bounds for length 73

Fortunately, there is a way to work it around that does allow the JavaFX plugins to install and, then, everything works fine, see:
{flexdoc-xml}/integrations/maven/plugin/pom_with_DiagramKit.xml
Yet, a possibility that something about that may break in the future (and require more workarounds) remains.
First, you need to install «FlexDoc/XML+DiagramKit Maven Plugin». For how to do it, please see:
FlexDoc/XML | Integrations | Maven Integration | Installation | Installation with DiagramKit
After having installed the Maven plugin successfully, you may run a demo Maven project that uses DiagramKit (i.e. generates XML schema documentation with diagrams), which is found at:
{flexdoc-xml}/DiagramKit/maven/pom.xml
It shows how to configure «FlexDoc/XML+DiagramKit Maven Plugin» to generate framed HTML XML schema documentation by the XML schema located at http://www.w3.org/2001/XMLSchema.xsd using FlexDoc/XML | XSDDoc | FramedDoc.tpl, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

Here is the project POM file:

FlexDoc/XML Maven Plugin is identified in this case as: xyz.flexdoc.xml:maven-plugin-with-diagramkit:1.0

pom.xml

<project>
...
<!-- Specify properties (i.e. variables for further usage) -->
<properties>
<!-- FlexDoc/XML home directory -->
<FDH>C:\flexdoc-xml</FDH>
</properties>
...
<!--
Reporting section.
All reports for "Project Reports" page of the Maven-generated site should be specified here.
-->
<reporting>
<plugins>
...
<!-- Setup some Maven plugin versions that work properly (Aug 2021) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.7</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.9</version>
</plugin>
...
<!-- Configure FlexDoc/XML Maven plugin -->
<plugin>
<groupId>xyz.flexdoc.xml</groupId>
<artifactId>maven-plugin-with-diagramkit</artifactId>
<version>1.0</version>
<configuration>
<!-- Specifying command-line parameters for FlexDoc/XML Generator -->
<generatorParams>
<!-- Specify DiagramKit as Element Image Provider -->
<param>-m:IMAGE_PROVIDER=DiagramKit</param>
<!-- The main template -->
<param>-template</param>
<param>${FDH}\templates\XSDDoc\FramedDoc.tpl</param>
<!-- Pass template parameter -->
<param>-p:docTitle</param>
<param>XML Schema for XML Schemas</param>
<!-- Specify the output format -->
<param>-format</param>
<param>HTML</param>
<!-- Suppress showing up the generator GUI -->
<param>-nodialog</param>
<!-- Suppress most of the generator messages -->
<param>-quiet</param>
<!--
Specify one or many data source XML files to be processed by the specified template.
(Both local pathnames and URLs are allowed.)
In this example, it is an XML schema to be documented.
-->
<param>http://www.w3.org/2001/XMLSchema.xsd</param>
</generatorParams>
<!--
Specify the output directory name.
The plugin will convert it into the absolute pathname of the output directory,
which is passed further both to Maven and to FlexDoc/XML Generator (via -d option).
-->
<outputFolder>xsddoc</outputFolder>
<!-- For the Maven project-reports page -->
<name>XSDDoc</name>
<description>XML Schema for XML Schemas</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>

To run that POM file, you can use a Windows batch file specified like the following: 

set JAVA_HOME=C:\Program Files\Java\jdk-17
set M2_HOME=C:\apache-maven
set MAVEN_OPTS=-Xms1024m -Xmx2048m
call %M2_HOME%\bin\mvn.bat site:site

Note that it should be started from the directory containing the pom.xml file.

Using JavaFX SDK

Instead of relying on JavaFX Maven plugins (as described above), you may install JavaFX SDK separately and use it with Maven as well.

You will need to install «FlexDoc/XML Maven Plugin» as described for the default case:

FlexDoc/XML | Integrations | Maven Integration | Installation
Then, you may run a demo Maven project that uses DiagramKit + JavaFX SDK, which is found at:
{flexdoc-xml}/DiagramKit/maven/pom_with_JavaFX_SDK.xml
It shows how to configure «FlexDoc/XML Maven Plugin» to generate framed HTML XML schema documentation by the XML schema located at http://www.w3.org/2001/XMLSchema.xsd using FlexDoc/XML | XSDDoc | FramedDoc.tpl, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

Here is the project POM file:

FlexDoc/XML Maven Plugin is identified in this case as: xyz.flexdoc.xml:default-maven-plugin:1.0

pom_with_JavaFX_SDK.xml

<project>
...
<!-- Specify properties (i.e. variables for further usage) -->
<properties>
<!-- FlexDoc/XML home directory -->
<FDH>C:\flexdoc-xml</FDH>
<!-- The pathname of your JavaFX SDK 'lib' directory -->
<JFX>C:\javafx-sdk-17\lib</JFX>
<!-- The class path to JavaFX modules necessary to run DiagramKit -->
<JFX_CLASSPATH>
${JFX}\javafx.base.jar;${JFX}\javafx.graphics.jar;${JFX}\javafx.swing.jar
</JFX_CLASSPATH>
</properties>
...
<!--
Reporting section.
All reports for "Project Reports" page of the Maven-generated site should be specified here.
-->
<reporting>
<plugins>
...
<!-- Setup some Maven plugin versions that work properly (Aug 2021) -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>3.7</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-project-info-reports-plugin</artifactId>
<version>2.9</version>
</plugin>
...
<!-- Configure FlexDoc/XML Maven plugin -->
<plugin>
<groupId>xyz.flexdoc.xml</groupId>
<artifactId>default-maven-plugin</artifactId>
<version>1.0</version>
<configuration>
<!-- Specifying command-line parameters for FlexDoc/XML Generator -->
<generatorParams>
<!-- Specify DiagramKit as Element Image Provider -->
<param>-m:IMAGE_PROVIDER=DiagramKit</param>
<!--
Specify Element Image Provider class path.
Since both FlexDoc/XML Maven Plugin and Generator called from it are executed in non-modular mode,
any special Java classes necessary to run the Element Image Provider must be specified here!
-->
<param>-m:IMAGE_PROVIDER_CLASSPATH=${FDH}\lib\flexdoc-xml-diagramkit.jar;${JFX_CLASSPATH}</param>
<!-- The main template -->
<param>-template</param>
<param>${FDH}\templates\XSDDoc\FramedDoc.tpl</param>
<!-- Pass template parameter -->
<param>-p:docTitle</param>
<param>XML Schema for XML Schemas</param>
<!-- Specify the output format -->
<param>-format</param>
<param>HTML</param>
<!-- Suppress showing up the generator GUI -->
<param>-nodialog</param>
<!-- Suppress most of the generator messages -->
<param>-quiet</param>
<!--
Specify one or many data source XML files to be processed by the specified template.
(Both local pathnames and URLs are allowed.)
In this example, it is an XML schema to be documented.
-->
<param>http://www.w3.org/2001/XMLSchema.xsd</param>
</generatorParams>
<!--
Specify the output directory name.
The plugin will convert it into the absolute pathname of the output directory,
which is passed further both to Maven and to FlexDoc/XML Generator (via -d option).
-->
<outputFolder>xsddoc</outputFolder>
<!-- For the Maven project-reports page -->
<name>XSDDoc</name>
<description>XML Schema for XML Schemas</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>

To run that POM file, you can use a Windows batch file specified like the following: 

set JAVA_HOME=C:\Program Files\Java\jdk-17
set M2_HOME=C:\apache-maven
set MAVEN_OPTS=-Xms1024m -Xmx2048m
call %M2_HOME%\bin\mvn.bat -f pom_with_JavaFX_SDK.xml site:site
Notes:
Copyright© 2021 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.flexdoc.xyz or e-mail to: support@flexdoc.xyz