FlexDoc/XML - DiagramKit - FAQ

DiagramKit Settings
Component Properties
Generator Setups

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):

The pathname of flexdoc-xml-diagramkit.jar must be included in Java module/class path.
The JavaFX modules, on which DiagramKit depends
- javafx.base
- javafx.graphics
- javafx.swing
also must be found on the Java module/class path:
- either as the part of the custom JRE
- or specified directly in the case of stand-alone JavaFX SDK
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.
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"?>

</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:

Using JavaFX Maven plugins – the default Maven distribution of JavaFX (which exists indeed).
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

...

<FDH>C:\flexdoc-xml</FDH>

</properties>

...

...

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-site-plugin</artifactId>

</plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-project-info-reports-plugin</artifactId>

</plugin>

...

<groupId>xyz.flexdoc.xml</groupId>

<artifactId>maven-plugin-with-diagramkit</artifactId>

<param>-m:IMAGE_PROVIDER=DiagramKit</param>

<param>-template</param>

<param>${FDH}\templates\XSDDoc\FramedDoc.tpl</param>

<param>-p:docTitle</param>

<param>XML Schema for XML Schemas</param>

<param>-format</param>

<param>-nodialog</param>

<param>-quiet</param>

<param>http://www.w3.org/2001/XMLSchema.xsd</param>

</generatorParams>

<outputFolder>xsddoc</outputFolder>

<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

...

<FDH>C:\flexdoc-xml</FDH>

<JFX>C:\javafx-sdk-17\lib</JFX>

<JFX_CLASSPATH>

${JFX}\javafx.base.jar;${JFX}\javafx.graphics.jar;${JFX}\javafx.swing.jar

</JFX_CLASSPATH>

</properties>

...

...

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-site-plugin</artifactId>

</plugin>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-project-info-reports-plugin</artifactId>

</plugin>

...

<groupId>xyz.flexdoc.xml</groupId>

<artifactId>default-maven-plugin</artifactId>

<param>-m:IMAGE_PROVIDER=DiagramKit</param>

<param>-m:IMAGE_PROVIDER_CLASSPATH=${FDH}\lib\flexdoc-xml-diagramkit.jar;${JFX_CLASSPATH}</param>

<param>-template</param>

<param>${FDH}\templates\XSDDoc\FramedDoc.tpl</param>

<param>-p:docTitle</param>

<param>XML Schema for XML Schemas</param>

<param>-format</param>

<param>-nodialog</param>

<param>-quiet</param>

<param>http://www.w3.org/2001/XMLSchema.xsd</param>

</generatorParams>

<outputFolder>xsddoc</outputFolder>

<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:

As the name of this POM file is different from the default 'pom.xml', it must be specified directly on the Maven command-line using -f option.
The batch file should be started from the directory containing pom_with_JavaFX_SDK.xml!