FlexDoc/XML - DiagramKit - Overview

What is DiagramKit?
Key Features
Running FlexDoc/XML + DiagramKit
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:

The diagrams are generated (as PNG image files) for the following components:
- Global and local elements
- Named complex types
- Element (model) groups
- Attribute groups
The focus of each diagram is to depict the result content model (elements/attributes) represented by the component:
- All possible child elements (their allowed compositions and cardinalities)
- When a depicted element is the head of a substitution group, a special branch attached to it shows all group member (substituting elements)
- All possible attributes (with their cardinalities)
at that, to show some other components involved in the derivation of the given one, including:
- Base type / element type (all components inherited from them are shown within a separate panel)
- Element/attribute groups
- Compositors (all/choice/sequence)
- Attribute prohibitions (only those specified in the definition of the given component)
Diagrams can also include descriptions to everything mentioned above (obtained from the corresponding <xs:annotation> elements). The wrapping of annotation text is optimized so as to maximally utilize the empty space arisen in the diagram because of its particular layout, thereby minimizing the bloating of the diagram by annotations themselves. This allows making the whole diagram more compact, as shown on this screenshot:

See also: FlexDoc/XML | DiagramKit | FAQ | Diagram Settings | How to show/hide annotations?
Since the version 2.0, DiagramKit supports showing in diagrams properties of elements and attributes.
Properties provide extra information such as the element/attribute type, content, facets, default value etc. Properties are displayed in the little grid embedded within the diagram node that depicts the element/attribute. Some of the properties are hyperlinked to the corresponding pieces of the documentation. For further details, please see: FlexDoc/XML | DiagramKit | FAQ | Component Properties.
The following screenshots show two diagrams of the same XSD component. The diagram on the left is with element/attribute properties. On the right, it is without the properties. Click on the screenshots to see each diagram within the corresponding documentation:
Our XSD diagrams largely follow the notation used in XMLSpy with the following differences:
- Both restricted and extended base types are equally shown in the diagram (including everything inherited from them).
  XMLSpy diagrams show only extended base types. The restricted base types are absent at all. The attributes inherited from them are joined with those defined in the given component, however highlighted with the yellow background.
- Abstract elements/complexTypes are highlighted with the italic font
- The annotations can be shown for anything that may contain them (including for base/element types) as
  - The first sentence of the annotation text
  - The full annotation text
  The wrapping of annotations is optimized so as to maximally use the empty space available in the diagram because of its layout, thereby making the whole diagram more compact.
- More diagram hyperlinks are generated (basically from any visible feature or label), including from the depictions not hyperlinked anyhow in XMLSpy diagrams:
  - From base/element types to their details (e.g. the title of the blue panel in the screenshots above)
  - From compositors (all/choice/sequence) to the corresponding locations in schema XML source where they are defined
  - From element/attribute wildcards to their details
  - From attribute groups to their details
  - From the values of some element/attribute properties
- Our diagrams also look cleaner because no collapse/expand buttons are shown on each diagram element.
What exactly the diagrams include and how they look can be configured with the special template parameters controlling DiagramKit (available in both XSDDoc/WSDLDoc):

See also:
- FlexDoc/XML | DiagramKit | FAQ | Diagram Settings
- FlexDoc/XML | DiagramKit | Parameters

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:

By installing some JRE (i.e. Java Runtime Environment) that already includes all necessary JavaFX modules by default
By installing JavaFX separately and specifying the path to its modules in the script/build files running FlexDoc/XML+DiagramKit

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
Using standard Java + JavaFX SDK

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:

Windows
Linux
macOS

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

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

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
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!
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.
Set a permission to allow executing generator.sh / designer.sh as a program.
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).

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
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:
- openjdk-17_macos-x64_bin.tar.gz – from https://jdk.java.net/17/
- openjfx-17.0.0.1_osx-x64_bin-jmods.zip – from https://gluonhq.com/products/javafx/
Although, these archives do include the macOS executables, they are properly signed by their creators. So, macOS won't have security problems with them.
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.
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.)
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:

To specify the location of your Java in the script files running FlexDoc/XML+DiagramKit.
To download JavaFX SDK from openjfx.io, install it on your system and specify the path to its modules in the script/build files running FlexDoc/XML+DiagramKit.
Concerning the compatibility of different versions of Java (JDK) and JavaFX. As of Aug 2021, all currently released JavaFX versions 11-17 will work with JDK 11 or later.

Using standard Java + JavaFX SDK on Windows

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

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
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"
Set a permission to allow executing generator.sh / designer.sh as a program.
Now, everything must be ready to run generator.sh / designer.sh.

Using standard Java + JavaFX SDK on macOS

Go to openjfx.io (or directly to https://gluonhq.com/products/javafx/) and download “JavaFX Mac OS X 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
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"
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.
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
Trial
Full

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:

License Manager Message

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:

License Manager Message

After clicking OK, you can continue using that template set (according to your license for it), however DiagramKit will be disabled:

No component diagrams will be generated
All DiagramKit related template parameters will be disabled too:

In order to use DiagramKit in that case, you can:

Uninstall your license for the given template set (then it will work in demo mode too)
Request a trial for DiagramKit
Purchase the full license for DiagramKit

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:

All diagrams will contain trial watermarks, like on this screenshot:
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.

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:

The license for DiagramKit covers only the generation of diagrams.
Although, you can combine it with any other FlexDoc/XML licenses, it makes sense to purchase it only together with a license for XSDDoc or WSDLDoc.

See Also: