FlexDoc/XML DiagramKit, Version 2.0

Table Of Contents

About DiagramKit

DiagramKit is the native diagramming engine of FlexDoc/XML. It works synchronously with the Template Processor and generates beautiful XSD component diagrams (with the support of all possible hyperlinks), which are immediately inserted in the documentation output produced by DiagramKit is implemented as a separate Java module 'flexdoc-xml-diagramkit.jar' found in the 'lib' directory of FlexDoc/XML installation.

DiagramKit uses of JavaFX – the newest Java graphics/GUI platform. So, in order to run it, either all necessary JavaFX modules must be included in the JRE itself (that executes FlexDoc/XML), or JavaFX SDK must be installed separately and the path to its modules specified in all command/build files running FlexDoc/XML+DiagramKit. See: Where to get JavaFX?

For further details about DiagramKit, please see: Docs | FlexDoc/XML | DiagramKit.

Content Files

These files and directories are found in 'DiagramKit/' subdirectory of FlexDoc/XML installation.

File / Directory Description
README.html this file
*.bat Windows batch files prepared to run FlexDoc/XML with DiagramKit:
generator.bat
  • Starts the Template Processor (generator) from command line
designer.bat
  • Launches the Template Designer (all DiagramKit-related functions will be active and you can invoke the generator integrated with DiagramKit)
linux/ Linux shell script files prepared to run FlexDoc/XML+DiagramKit:
linux/generator.sh
  • Starts the generator
linux/designer.sh
  • Launches the Template Designer
macOS/ macOS shell script files prepared to run FlexDoc/XML+DiagramKit:
macOS/generator.command
  • Starts the generator
macOS/designer.command
  • Launches the Template Designer
ant/ Ant example files:
ant/build.xml
  • Ant build file that shows how to call FlexDoc/XML+DiagramKit from Apache Ant to generate an XML Schema documentation with diagrams.
ant/make.bat
ant/make.sh
ant/make.command
  • Windows / Linux / macOS command files to run Ant Demo
maven/ A demo project that shows how to configure FlexDoc/XML Maven plugin so as to integrate it with DiagramKit to generate an XML Schema documentation with diagrams for the reports section of a Maven-generated site:
maven/pom.xml
maven/pom_with_JavaFX_SDK.xml
  • POM file for the case of Using JavaFX SDK. This POM file is used by site_with_JavaFX_SDK.(bat|sh|command) files.
maven/site.bat
maven/site.sh
maven/site.command
maven/site_with_JavaFX_SDK.bat
maven/site_with_JavaFX_SDK.sh
maven/site_with_JavaFX_SDK.command

Licensing

Being a complex piece of software that took lots of efforts to develop, DiagramKit requires separate licensing.

License Type Description
Demo License When no particular license for DiagramKit has been installed, the Demo License is activated, which 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.

That is exactly the case when you have just downloaded FlexDoc/XML and installed it. Then, you can immediately run it. Everything will work in demo mode. You don't need to request any trial for that!

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.
Trial License DiagramKit with full functionality and generate all possible diagrams (with all hyperlinks). However, there are following limitations:
  • All diagrams will contain trial watermarks.
  • All generated output documents will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages).
  • Any output documents or diagrams may be used only for evaluation of this software. Any other usage is prohibited!
  • Trial license is limited to 30 days.
The trial mode for DiagramKit does not affect your possibility to create/modify templates. This is controlled by your license for FlexDoc/XML SDK.

You can obtain a trial license for DiagramKit by this link: https://www.flexdoc.xyz/trial/?pid=flexdoc-xml-diagramkit2

Currently, the trial license for DiagramKit is included in “FlexDoc/XML (essential)” trial license pack

Full License Allows you using DiagramKit without any limitations. All diagrams will be generated clean (without any watermarks).

Anything else will depend on other your licenses.

See also:

Installation

License File

Store DiagramKit license file 'flexdoc-xml-diagramkit.license', which you may have received by e-mail, to {flexdoc-xml}/lib directory (near the flexdoc-xml.jar file).

The license for DiagramKit may be also included in a combined 'flexdoc-xml.license' file (along with other licenses), which should be also installed in the same location: {flexdoc-xml}/lib

Where to get JavaFX?

DiagramKit is implemented with the use JavaFX – the newest Java graphics/GUI platform. So, 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, may be is too complicated for ordinary users, and breaks down the whole idea of using a 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, Linux and macOS 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, Linux and macOS.

Once you have downloaded FlexDoc/XML archive and unpacked it at some location, which we shall designate as '{flexdoc-xml}', go to flexdoc.xyz/downloads/ 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-17_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 the directory:

    {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 Linux

  1. Unpack flexdoc-jre-17_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 the directory:

    {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 FlexDoc JRE on macOS

As of macOS version 11 (Big Sur), Apple has tightened the «security control» so much that in order to install and run any macOS executables, they must come either from Apple Store or «signed» with an Apple Developer Account, which is quite expensive to maintain. Since, we are not a true macOS developer and the number of potential FlexDoc/XML users, who work on macOS, is too small, we do not see it reasonable to overcome that hurdle directly.

However, we take advantage of that Apple still allows the macOS users to install and run on their computer the executables built by those users themselves. So, instead of preparing a ready to install & run FlexDoc JRE, we offer you an easy way to build it by yourself (which differs from the former mostly by the size of the downloaded archive file).

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

    {flexdoc-xml}/build_jre

    It does not contain a ready to use JRE. However, it contains all files necessary to build it, namely: Although, these archives do include the macOS executables, they are properly signed by their creators. So, macOS won't have security problems with them.
  2. Now, in order to build the real JRE, you only need to execute the following script found in the same folder:

    {flexdoc-xml}/build_jre/build_jre.command

    See: How to make a macOS shell script file executable?

  3. After executing 'build_jre.command', a new directory will be created:

    {flexdoc-xml}/jre

    That will be your Java to run FlexDoc/XML! (The 'build_jre' folder can be deleted then.)
  4. 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.

    See: How to make a macOS shell script file executable?

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 (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX Windows SDK”, e.g.:

    openjfx-17_windows-x64_bin-sdk.zip

    Do not download “JavaFX Windows jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    C:\javafx-sdk-17

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

    Edit generator.bat / designer.bat found there as follows:

    In 'JAVA_HOME' variable, specify the location of your Java installation directory, e.g.:

    set JAVA_HOME=C:\Program Files\Java\jdk-17

    In 'PATH_TO_FX' variable, specify the location of JavaFX SDK 'lib' directory, e.g.:

    set PATH_TO_FX=C:\javafx-sdk-17\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 Linux

  1. Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX Linux SDK” archive, e.g.:

    openjfx-17_linux-x64_bin-sdk.zip

    Do not download “JavaFX Linux jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    /home/user/javafx-sdk-17

  2. Go to the directory: {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 found there as follows:

    In 'JAVA_HOME' variable, specify the location of your Java installation directory, e.g.:

    JAVA_HOME="/home/user/jdk-17"

    In 'PATH_TO_FX' variable, specify the location of JavaFX SDK 'lib' directory, e.g.:

    PATH_TO_FX="/home/user/javafx-sdk-17/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.

Using standard Java + JavaFX SDK on macOS

  1. Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX macOS SDK” archive, e.g.:

    openjfx-17_osx-x64_bin-sdk.zip

    Do not download “JavaFX Mac OS X jmods” archive also available there! That is not a proper JavaFX SDK. Although, JMOD files contain some compiled images of Java modules, they can be processed only by jlink command, used to build a custom JRE.

    Unpack the downloaded archive somewhere. You will get a folder like this:

    /Users/Shared/javafx-sdk-17

  2. Go to the directory: {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 found there as follows:

    In 'JAVA_COMMAND' variable, specify the command used to invoke JVM (Java 11.x or later), e.g.:

    JAVA_COMMAND="java"

    In 'PATH_TO_FX' variable, specify the location of JavaFX SDK 'lib' directory, e.g.:

    PATH_TO_FX="/Users/Shared/javafx-sdk-17/lib"

  3. Now, everything must be ready to run generator.command / designer.command.

    See: How to make a macOS shell script file executable?

Running Ant Demo

  1. Download and install FlexDoc JRE as described in Using FlexDoc JRE.

  2. Go to the directory: {flexdoc-xml}/DiagramKit/ant/

    Edit the OS-specific script file to specify the locations of your Java and Ant installations:

  3. Run that make script file
For more details about running FlexDoc/XML+DiagramKit with Apache Ant, please see: Docs | FlexDoc/XML | DiagramKit | FAQ | Generator Setups | Running with Apache Ant

Running Maven Demo

FlexDoc/XML includes a Maven plugin found at:
{flexdoc-xml}/DiagramKit/maven/ – see also index.html in that folder
However, linking DiagramKit to this is not straightforward because DiagramKit requires JavaFX, whose 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
  2. Using JavaFX SDK – installed separately

See also: Docs | FlexDoc/XML | DiagramKit | FAQ | Generator Setups | Running with Apache Maven

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

The step-by-step instruction:

  1. Install “FlexDoc/XML+DiagramKit Maven Plugin”. For how to do it, please see:

    {flexdoc-xml}/integrations/maven/index.html | Installation | Installation with DiagramKit

  2. Go to the directory: {flexdoc-xml}/DiagramKit/maven/

    Edit the OS-specific script file to specify the locations of your Java and Maven installations:

    Since FlexDoc/XML Maven Plugin (along with FlexDoc/XML Template Processor, DiagramKit and JavaFX) will be executed by the same JVM as Maven, you should ensure that enough memory has been allocated to it. That can be done in the script running Maven with a setting like the following:

    export MAVEN_OPTS="-Xms1024m -Xmx2048m"

  3. Run that site script 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.

The step-by-step instruction:

  1. Install “FlexDoc/XML Maven Plugin” as described for the default case:

    {flexdoc-xml}/integrations/maven/index.html | Installation

  2. Download and install JavaFX SDK as described in Using standard Java + JavaFX SDK.
  3. Go to the directory: {flexdoc-xml}/DiagramKit/maven/

    Edit 'pom_with_JavaFX_SDK.xml' found there to specify the pathname of JavaFX SDK 'lib' directory in the following line:

    <!-- Specify the pathname of JavaFX SDK 'lib' directory -->
    <JFX>C:/javafx-sdk-17/lib</JFX>

    Under macOS, to obtain the absolute pathname of a file/directory, drag it from the Finder into the TextEdit window.

  4. Edit the OS-specific script file to specify the locations of your Java and Maven installations:
    Since FlexDoc/XML Maven Plugin (along with FlexDoc/XML Template Processor, DiagramKit and JavaFX) will be executed by the same JVM as Maven, you should ensure that enough memory has been allocated to it. That can be done in the script running Maven with a setting like the following:

    export MAVEN_OPTS="-Xms1024m -Xmx2048m"

  5. Run that site_with_JavaFX_SDK script file

Tips

How to make a macOS shell script file executable?

Because of security control, all macOS shell script files found in the downloaded FlexDoc/XML archive cannot be executed straight. However, that is easy to overcome as described below for a reference script.command file:
  1. First, open script.command with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu.

    With that procedure, you will sign script.command as its “owner/creator”, which is a precondition to be able running it.

  2. On top of that, you will need also to assign script.command 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 script.command from the Finder into the Terminal window). Then, press Enter.

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

Getting Help

Change Log

Version 2.0

Version 1.1

Migration to modular Java. DiagramKit implementation has been moved from 'flexdoc-xml.jar' to the separate module 'flexdoc-xml-diagramkit.jar'.

Copyright© 2021 Filigris Works, Leonid Rudy Softwareprodukte