FlexDoc/XML - DiagramKit

FlexDoc/XML v1.13 released including DiagramKit 2.1. See its new README/Change Log.

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

  1. What is DiagramKit?
  2. Key Features
  3. Running FlexDoc/XML + DiagramKit
  4. Licensing / Processing Modes

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 that provides 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. Running FlexDoc/XML + DiagramKit

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, 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. Here is the step-by-step instruction according to your OS: We assume that you have already downloaded FlexDoc/XML archive and unpacked it at some location, which we shall designate as '{flexdoc-xml}'.

Using FlexDoc JRE on Windows

  1. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Windows/x64 (zip)”

    You should get this archive: flexdoc-jre-17_windows.zip
  2. Unpack it 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!
  3. 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 Linux

  1. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | Linux/64 (tar.gz)”

    You should get this archive: flexdoc-jre-17_linux.tar.gz
  2. Unpack it 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!
  3. 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.

  4. Set a permission to allow executing generator.sh / designer.sh as a program.
  5. 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. Go to the downloads page once again and download from there:

    “FlexDoc JRE (OpenJDK+JavaFX) to run FlexDoc/XML+DiagramKit | macOS/64 (zip)”

    You should get this archive: flexdoc-jre-17_macOS.zip
  2. Unpack it 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.
  3. 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

    Although, macOS won't allow you to run 'build_jre.command' straight, that is easy to overcome:
    • First, open 'build_jre.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 'build_jre.command' as its owner/creator, which is a precondition to be able running it.
    • On top of that, you will need also to assign 'build_jre.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 'build_jre.command' from the Finder into the Terminal window). Then, press Enter.
    Now at last, you can run 'build_jre.command' from the Finder just by clicking twice on it.
  4. 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.)
  5. 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.

    But again, to be able to run any of those script files, first you need to
    • Resave the script file using TextEdit.
    • Assign it with the executable privilege (by running the Terminal, typing in it 'chmod u+x' followed by a space, dragging script.command into the Terminal window and pressing Enter).

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

    ::----------------------------------------------------------------------
    :: Specify the location of JavaFX SDK 'lib' directory, e.g.:
    :: C:\javafx-sdk-17\lib
    ::
    :: Note: When you use FlexDoc JRE, leave this setting empty
    ::----------------------------------------------------------------------
     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: {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-17"

    #----------------------------------------------------------------------
    # Specify the location of JavaFX SDK 'lib' directory, e.g.:
    # /home/user/javafx-sdk-17/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
     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: {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-17/lib
    #
    # Note: When you use FlexDoc JRE, leave this setting empty
    #----------------------------------------------------------------------
     PATH_TO_FX="/Users/Shared/javafx-sdk-17/lib"
  3. To be able to run generator.command, first, open it with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. By doing that you will sign generator.command as its owner/creator, which is a precondition to be able running it.

    Then, you need to assign generator.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 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.

Integration with Ant/Maven

A demo about that you can find in your FlexDoc/XML installation:
{flexdoc-xml}/DiagramKit/ant/
{flexdoc-xml}/DiagramKit/maven/
{flexdoc-xml}/DiagramKit/README.html
See Also:

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” preselected in the «Product» field.

“FlexDoc/XML” 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: