Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
DiagramKit
Integrations
 DocFlex/Javadoc
Overview
Documentation
JavadocClassic
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/XML - DiagramKit

  1. What is DiagramKit?
  2. Key Features
  3. Technical Requirements
  4. Usage
  5. Licensing / Processing Modes

1.  What is DiagramKit?

DiagramKit is the DocFlex/XML native diagramming engine (independent on any third-party software). 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). It is included in DocFlex/XML software and will work by default.

DiagramKit is implemented as a diagramming plugin, which is a replaceable part of DocFlex/XML, whose job is to provide some graphical representations of XML elements. It is another add-on to DocFlex/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)
  • 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
    • 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
    • Our diagrams also look cleaner because no collapse/expand buttons are shown on each diagram element.
  • The generation of diagrams is controlled by the “Diagramming | DiagramKit” template parameter group (in both XSDDoc/WSDLDoc), which is shown on the following screenshot. Here you can also customize a little bit the diagram look&feel. Click on the screenshot to see the corresponding parameter description:

    Note that the “DiagramKit” parameter group is enabled only when the DiagramKit plugin is active (see Usage).

3.  Technical Requirements

DiagramKit is implemented entirely using JavaFX 8 (the newest Java graphics/GUI platform) without involvement of anything else (e.g. XMLSpy etc). Consequently, DiagramKit will work anywhere Java 8 (or later) + JavaFx work. In particular, we've tested it on the following operating systems:
  • MS Windows
  • macOS
  • Linux
On all of them, you can equally run XSDDoc/WSDLDoc + DiagramKit from both Ant and Maven.

Notes:

  • Officially, JavaFx is included in Java SE (both JRE/JDK) since Java 8. So, you just need to install Java 8 (or later) to have everything ready to run DiagramKit.

    You can freely download and install the most recent version of Java (JRE) from Java Technology web-site: http://www.oracle.com/technetwork/java/

  • On Linux, DiagramKit will work also in headless mode (e.g. on a server). However, you need to make sure that X-Windows (X11) System is installed and working there. Otherwise, JavaFX cannot initialize itself. Since a headless-Linux (i.e. without graphics) typically comes without X-Windows System, you need to install (and launch) it separately.

    Note that for some Linux distributions, JavaFx may need to be installed separately after JDK, e.g.:
    sudo apt-get update
    sudo apt install openjdk-8-jre-headless
    sudo apt-get install openjfx

4.  Usage

Since DiagramKit is a diagramming plugin, it can be replaced with any other such a plugin (e.g. XMLSpy Integration or OxygenXML Integration), which is specified on the generator and template designer Java command line using -m option:
-m:IMAGE_PROVIDER_CLASS=diagramming-plugin-class
where 'diagramming-plugin-class' is a Java class implementing the plugin entry point. For instance, specifying DiagramKit in that way would look as follows:
-m:IMAGE_PROVIDER_CLASS=com.docflex.xml.xsd.DiagramKit
However, 'IMAGE_PROVIDER_CLASS' is a macro that is expanded in the template set's XML Type config file. Unless that macro is specified on the command line, its default value will be used, which in case of XSDDoc/WSDLDoc is also assigned in the same config file with 'com.docflex.xml.xsd.DiagramKit'.

So, unless -m:IMAGE_PROVIDER_CLASS option is used on the command line (which is exactly the case when you run {docflex-xml}\bin\generator.bat), DiagramKit will be activated by default with any XSDDoc/WSDLDoc main template.

For further information, please see:

5.  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, which allows 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 DocFlex/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!

When 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 none 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:
  • 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
If you want neither of the above, you can suppress the appearance of the license manager message using '-m:IMAGE_PROVIDER_CLASS=' option on the generator Java command line. For instance, here is how you should modify the last command in the supplied generator.bat:
"%JAVA_HOME%\bin\java" %JAVA_OPTIONS% -cp "%CLASS_PATH%" com.docflex.xml.Generator -m:IMAGE_PROVIDER_CLASS=
That effectively means setting the generator to use no diagramming plugin.

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 “DocFlex/XML (essential)” preselected in the «Product» field.

“DocFlex/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 'docflex-xml.license' file, which you will receive by email.

The license file should be saved in DocFlex/XML 'lib' directory (near 'docflex-xml.jar' file):

{docflex-xml}/lib/

where '{docflex-xml}' denotes your DocFlex/XML installation directory.

See Also:

Full Mode

Full mode is activated in the presence of a Full License for “DocFlex/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 DocFlex/XML licenses, it makes sense to purchase it only together with a license for XSDDoc or WSDLDoc.
See Also:

Copyright© 2018 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.