FlexDoc/XML - DiagramKit

This feature is included in FlexDoc/XML archive, which is ready for downloads now!

  1. What is DiagramKit?
  2. Key Features
  3. Installation
  4. Licensing / Processing Modes
  5. Settings Detail
  6. Generator Setups

1. What is DiagramKit?

DiagramKit is the FlexDoc/XML native diagramming engine. It creates beautiful XSD component diagrams, which can be generated/inserted simultaneously along with the documentation generated by XSDDoc/WSDLDoc (with the support of all possible hyperlinks).

DiagramKit is implemented as a diagramming plugin, which is a replaceable part of FlexDoc/XML, whose job is to provide some graphical representations of XML elements. It is another add-on to FlexDoc/XML and licensed separately.

Below are two sample diagrams generated by DiagramKit (click on the screenshots to view each diagram inside the documentation):

For more sample documentation with diagrams generated by DiagramKit, please see:

2. Key Features

Generation of XSD (XML Schema) component diagrams:

3. Installation

Since DiagramKit is a part of FlexDoc/XML software, it will be pre-installed together with FlexDoc/XML.
Unfortunately, you won't be able to run DiagramKit immediately with any your Java setup. If you try, you will get an error like this:
Error occurred during initialization of boot layer
java.lang.module.FindException: Module javafx.base not found, required by flexdoc.xml.diagramkit
That's because DiagramKit requires JavaFX – the newest Java graphics/GUI platform, which is not included any longer in the standard Java SE. So, the installation of DiagramKit comes down to the installation of JavaFX and specifying its location in the script/build files running FlexDoc/XML+DiagramKit.

Where to get JavaFX?

In order to run DiagramKit, all JavaFX dependencies must be resolved. That can be achieved either:
Before Java 11, JavaFX was a part of the standard Java SE. So, no problem existed with those JavaFX dependencies, and FlexDoc/XML+DiagramKit could be run immediately with any new Java version.

But since Java 11, Oracle has moved JavaFX into a separate project found on openjfx.io. Now, those who need JavaFX should download JavaFX SDK separately from there, install it and specify all JavaFX dependencies in their Java application according to that installation. That, of course, is too complicated for many ordinary users, and breaks down the whole idea of using some generic JRE pre-installed on user's computer (independently on FlexDoc/XML).

However, as a compensation for all that perturbation (and actually as its goal), since Java 11, anyone could build their own custom JRE (called «runtime image») that would include in itself any 3rd party modules necessary to run a given application on a particular computer platform.

Now, we took that new opportunity and prepared our own FlexDoc JRE (OpenJDK+JavaFX images) to run FlexDoc/XML+DiagramKit on Windows, macOS and Linux immediately. Just download this Java from our website and don't bother with anything else!

Both possibilities are described below:

Using FlexDoc JRE

We offer a custom JRE (called «FlexDoc JRE»), which is a set of {OpenJDK+JavaFX} images prepared to run FlexDoc/XML+DiagramKit immediately on Windows, macOS and Linux.

Once you have downloaded FlexDoc/XML archive and unpacked it at some location, which we shall designate as '{flexdoc-xml}', go to downloads page once again and download from there:

“FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit”
according to your OS. You should get one of these archives:

Using FlexDoc JRE on Windows

  1. Unpack flexdoc-jre-14_windows.zip into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}\jre

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  2. Go to: {flexdoc-xml}\DiagramKit\

    Now, you can immediately start generator.bat and designer.bat found there to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

Using FlexDoc JRE on macOS

These steps were tested on macOS Catalina (10.15)

  1. Unpack flexdoc-jre-14_macOS.tar.gz into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/jre

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  2. Go to: {flexdoc-xml}/DiagramKit/macOS/

    You will find generator.command and designer.command prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

  3. To be able to run generator.command, first you need to assign it with the executable privilege.

    Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter.

    Now, you can run generator.command from the Finder just by clicking twice on it.

  4. Equally with designer.command.

Using FlexDoc JRE on Linux

  1. Unpack flexdoc-jre-14_linux.tar.gz into {flexdoc-xml}. You will have a folder:

    {flexdoc-xml}/jre

    That will be your Java to run FlexDoc/XML. You don't need to install anything else!
  2. Go to: {flexdoc-xml}/DiagramKit/linux/

    You will find generator.sh and designer.sh prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

  3. Set a permission to allow executing generator.sh / designer.sh as a program.
  4. Now, everything must be ready to run generator.sh / designer.sh!

Using standard Java + JavaFX SDK

If for some reasons you cannot use our FlexDoc JRE (for instance, in case of Maven), you may use any other (standard) Java installed on your system.

Then, you will need:

Using standard Java + JavaFX SDK on Windows

  1. Go to openjfx.io and download “JavaFX Windows SDK” archive, e.g.:

    openjfx-14_windows-x64_bin-sdk.zip

    Unpack it somewhere. You will get a folder like this:

    C:\javafx-sdk-14

  2. Go to: {flexdoc-xml}\DiagramKit\

    Edit generator.bat / designer.bat found in that directory, in these lines:

    ::----------------------------------------------------------------------
    :: Specify the location of Java 11 (or later) here. The default setting:
    ::
    :: set JAVA_HOME=%FDH%\jre
    ::
    :: assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    :: which you can download from http://www.flexdoc.xyz/downloads/
    ::----------------------------------------------------------------------
    set JAVA_HOME=C:\Program Files\Java\jdk-14

    ::----------------------------------------------------------------------
    :: Specify the location of JavaFX SDK 'lib' directory, e.g.:
    :: C:\javafx-sdk-14\lib
    ::
    :: Note: When you use FlexDoc JRE, leave this setting empty
    ::----------------------------------------------------------------------
    set PATH_TO_FX=C:\javafx-sdk-14\lib
  3. Now, you can start generator.bat / designer.bat to run Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

Using standard Java + JavaFX SDK on macOS

  1. Go to openjfx.io and download “JavaFX Mac OS X SDK” archive, e.g.:

    openjfx-14_osx-x64_bin-sdk.zip

    Unpack it somewhere. You will get a folder like this:

    /Users/Shared/javafx-sdk-14

  2. Go to: {flexdoc-xml}/DiagramKit/macOS/

    You will find generator.command and designer.command prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

    Edit generator.command / designer.command in these lines:

    #----------------------------------------------------------------------
    # Specify the command used to invoke JVM (Java 11 or later) here.
    # The default setting:
    #
    # JAVA_COMMAND="$FDH/jre/bin/java"
    #
    # assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    # which you can download from http://www.flexdoc.xyz/downloads/
    #----------------------------------------------------------------------
    JAVA_COMMAND="java"

    #----------------------------------------------------------------------
    # Specify the location of JavaFX SDK 'lib' directory, e.g.:
    # /Users/Shared/javafx-sdk-14/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
    PATH_TO_FX="/Users/Shared/javafx-sdk-14/lib"
  3. To be able to run generator.command, first you need to assign it with the executable privilege.

    Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter.

    Now, you can run generator.command from the Finder just by clicking twice on it.

  4. Equally with designer.command.

Using standard Java + JavaFX SDK on Linux

  1. Go to openjfx.io and download “JavaFX Linux SDK” archive, e.g.:

    openjfx-14_linux-x64_bin-sdk.zip

    Unpack it somewhere. You will get a folder like this:

    /home/user/javafx-sdk-14

  2. Go to: {flexdoc-xml}/DiagramKit/linux/

    You will find generator.sh and designer.sh prepared to run respectively Template Processor / Template Designer with DiagramKit activated as the diagramming engine.

    Edit generator.sh / designer.sh in these lines:

    #----------------------------------------------------------------------
    # Specify the location of Java 11 (or later) here. The default setting:
    #
    # JAVA_HOME="$FDH/jre"
    #
    # assumes the installation of FlexDoc JRE (OpenJDK+JavaFX),
    # which you can download from http://www.flexdoc.xyz/downloads/
    #----------------------------------------------------------------------
    JAVA_HOME="/home/user/jdk-14"

    #----------------------------------------------------------------------
    # Specify the location of JavaFX SDK 'lib' directory, e.g.:
    # /home/user/javafx-sdk-14/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
    PATH_TO_FX="/home/user/javafx-sdk-14/lib"
  3. Set a permission to allow executing generator.sh / designer.sh as a program.
  4. Now, everything must be ready to run generator.sh / designer.sh!

4. Licensing / Processing Modes

DiagramKit works with both XSDDoc and WSDLDoc, however, it is licensed separately.

That's because you can choose to use another diagramming plugin (e.g. XMLSpy Integration or OxygenXML Integration) or none at all instead.

To accommodate all possibilities concerning licensing, DiagramKit will work in the following modes:

Demo Mode

When you have no particular license for DiagramKit, the Demo License is activated that enables a special demo mode. The purpose of that mode is to allow you without much hassle to see what DiagramKit basically can and in some cases even to use it for free.

In demo mode, DiagramKit will work together with either XSDDoc/WSDLDoc when no other licenses are installed for both DiagramKit and the given template set. If you run XSDDoc or WSDLDoc, you will see a message like this:

Just click OK to continue.

In demo mode, DiagramKit will generate only limited number of component diagrams. How many depends on the demo limits of a particular main template. However, any diagrams generated in demo mode will be complete and without trial markers.

When demo mode is disabled

Because of programming limitations, DiagramKit can work in demo mode only with a template set (i.e. XSDDoc/WSDLDoc) also running in demo mode. When you already have a Full License for that template set (and no for DiagramKit), you will see a message like this:

After clicking OK, you can continue using that template set (according to your license for it), however DiagramKit will be disabled: In order to use DiagramKit in that case, you can: See Also:

Trial Mode

Trial mode is activated in the presence of a Trial License for DiagramKit, which will work with full functionality and generate all possible diagrams (with all hyperlinks). However, there are following limitations: You can request a trial license by clicking this button:

Then, you will be redirected to Try | Trial License page with “FlexDoc/XML (essential)” preselected in the «Product» field.

“FlexDoc/XML (essential)” means that you get in fact not a single but a package of trial licenses (corresponding all full ones): all of them together in a single 'flexdoc-xml.license' file, which you will receive by email.
The license file should be saved in FlexDoc/XML 'lib' directory (near 'flexdoc-xml.jar' file):

{flexdoc-xml}/lib/

where '{flexdoc-xml}' denotes your FlexDoc/XML installation directory.

See Also:

Full Mode

Full mode is activated in the presence of a Full License for “FlexDoc/XML DiagramKit”. It allows you using DiagramKit without limitations. All diagrams will be generated clean (without any watermarks).

Please Note:

See Also:

5. Settings Detail

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 (for examples, see Generator Setups).

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. That file must be included in the Java module path in order to run FlexDoc/XML+DiagramKit.

Besides that, the service name itself must be specified on the Java command line (that runs generator or template designer) using -m option as follows:

-m:IMAGE_PROVIDER=DiagramKit

Related Template Parameters

Besides the Java command-line settings required to setup DiagramKit as a whole, there are other settings, using which you can configure the generation of diagrams. Those settings are relevant only to a particular documentation generator (implemented as a template set) and exposed as template parameters (available in both XSDDoc/WSDLDoc). Click on the screenshot to see the corresponding parameter descriptions:

«DiagramKit» parameter group is enabled only when the plugin is active (see above).

See Also:

6. Generator Setups

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

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-oxygenxml.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-14\lib

:: FlexDoc/XML module path
set MODULE_PATH=%FDH%\lib\flexdoc-xml.jar;%FDH%\lib\flexdoc-xml-oxygenxml.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-14
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.

The following project POM file shows how to configure the 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 + DiagramKit, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

Since FlexDoc/XML Maven Plugin runs in the same Java thread as Maven, FlexDoc JRE cannot be used with it (because to run Maven you may need the full JDK). So, you can run DiagramKit with Maven only using JavaFX SDK.

pom.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-14\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 (on 2020-03-15). Otherwise, you'll get an exception -->
<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>flexdoc</groupId>
<artifactId>flexdoc-xml-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.xml file, you can use a Windows batch file specified like the following:

set JAVA_HOME=C:\Program Files\Java\jdk-14
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 Maven pom.xml file!