FlexDoc/XML - Oxygen XML Integration

This feature has been discontinued. Please, use DiagramKit instead!

1. Overview

This integration will let you generated XML schema / WSDL documentation (using XSDDoc / WSDLDoc templates) with the automatic insertion of component diagrams produced by Oxygen XML Editor, with the full support of diagram hyperlinks.

In the following text, Oxygen XML Editor will be referred also as OxygenXML

That, in effect, will turn the FlexDoc/XML+OxygenXML combination into a single unique documentation generator not available in any of these products. Click on the following screenshot to see a sample documentation generated with it:

You can also download this demo documentation by the link: xslt20-xsddoc.zip (5.4 MB)

Key Features

Possibility to run OxygenXML from FlexDoc/XML templates to perform specific tasks, namely:
- Launching OxygenXML's own XML schema documentation generator for the specified XML schemas with the specified options.
Associating the diagrams (and hyperlink image maps) generated by OxygenXML with the DSM elements representing the XML schema components in templates and making them available (via Image Control) to be inserted in the output documentation generated by FlexDoc/XML.
Automatic insertion of XSD component diagrams produced by OxygenXML into the XML schema documentation generated by FlexDoc/XML XSDDoc. The diagrams can be generated in the following formats:
- PNG
- GIF
- JPEG
which are fully supported both in HTML and RTF output.
Full support of diagram hyperlinks (in HTML output).
Processing of complex XML schemas with <xs:import>, <xs:include>, <xs:redefine> of other XML schemas and generating single documentation for all involved XML schemas together with all OxygenXML diagrams in place. (See also: Using XML Catalog.)
Possibility to run the unified FlexDoc/XML+OxygenXML template-driven documentation generators from both:
- Apache Ant
- Apache Maven
Running multiple instances of OxygenXML concurrently, so as to employ the multiprocessing capabilities of your system.
When you generate documentation by lots of independent XML schemas, OxygenXML must be run separately for each of them in order to generate the XSD diagrams. That takes substantial time. Running OxygenXML in multiple concurrent threads allows processing several XML schemas simultaneously. That may accelerate the generation of diagrams several times!
See also: FlexDoc/XML | XSDDoc | Parameters | Diagramming | OxygenXML Integration | Multithread Processing
Since both FlexDoc/XML and OxygenXML are based on Java, the integration is equally available on
- Windows
- macOS
- Linux
Note that there are special distributions of OxygenXML prepared for each of those systems!

Technical Requirements

Any edition of OxygenXML that includes its own XML Schema Documentation (for instance, “Oxygen XML Editor”).
Concerning which versions are supported, we have tested this integration starting from Oxygen XML 13. Actually, all comes down to the following:
- The schemaDocumentation.bat (or schemaDocumentation.sh under Linux) is included.
- All parameters/options of the OxygenXML's own doc-generator can be set via a special config-file passed as the schemaDocumentation.bat argument.
- It is also supported passing a custom XSLT style sheet, which receives as input some intermediate XML file (produced by OxygenXML) so as to generate from it any other type of output.
- The structure of that intermediate XML file is backward compatible with the one generated by Oxygen XML 15.
  The XSLT style sheet passed by the integration converts the XML file generated by OxygenXML into another XML file convenient for further processing by the integration Java code.
As long as those things remain the same in the future OxygenXML version, the current integration will work with them as well.
Java version 9 (or later) installed on your system.
A computer with 2 GB RAM (or more)

Licensing / Processing Modes

Being a complex piece of software, which took lots of efforts to develop, the OxygenXML Integration requires a separate licensing. Depending on your license, the integration may work in one of two different modes: full or trial, as described in the following table:

Processing	Description
Full Mode	The Full Mode is activated in the presence of a Full License for “FlexDoc/XML OxygenXML Integration”. This mode allows you to use the integration without any limitations. Once it is enabled, you may think about the integration as just another part of FlexDoc/XML executables. Anything else will depend on your other licenses.
Trial Mode	The Trial Mode is activated in the presence of a Trial License for “FlexDoc/XML OxygenXML Integration”. In this mode, the integration will work the same as in the full mode. However, no matter what your other licenses are the following limitations will be enforced: You may use the integration working in trial mode only during the limited period of time (30 days) provided by your Trial License. Any output documents generated in trial mode will be specifically distorted. Such documents may be used only for evaluation of this software. Any other usage is prohibited! The trial mode for OxygenXML Integration will not affect your possibility to create/modify templates. This is controlled by your license for FlexDoc/XML SDK!

Processing

Description

Full Mode

The Full Mode is activated in the presence of a Full License for “FlexDoc/XML OxygenXML Integration”.

This mode allows you to use the integration without any limitations. Once it is enabled, you may think about the integration as just another part of FlexDoc/XML executables.

Anything else will depend on your other licenses.

Trial Mode

The Trial Mode is activated in the presence of a Trial License for “FlexDoc/XML OxygenXML Integration”. In this mode, the integration will work the same as in the full mode. However, no matter what your other licenses are the following limitations will be enforced:

You may use the integration working in trial mode only during the limited period of time (30 days) provided by your Trial License.
Any output documents generated in trial mode will be specifically distorted. Such documents may be used only for evaluation of this software. Any other usage is prohibited!

The trial mode for OxygenXML Integration will not affect your possibility to create/modify templates. This is controlled by your license for FlexDoc/XML SDK!

See Also:

2. Getting Started

Since OxygenXML Integration is closely connected with the FlexDoc/XML core, all Java classes implementing it are included in the general FlexDoc/XML Java library: flexdoc-xml.jar.

However, to get it work, you will need to install a “FlexDoc/XML OxygenXML Integration” license and specify a few additional settings.

Obtain a License

The OxygenXML Integration requires a separate license, which you should receive by e-mail.

The license comes as a single 'flexdoc-xml-oxygenxml.license' file or it may be included in a combined 'flexdoc-xml.license' file (along with other licenses).

In either case, you should save the license file in the 'lib' directory of your FlexDoc/XML installation:

{flexdoc-xml}/lib

where the license is searched for by default (near 'flexdoc-xml.jar' file).

It is also possible to specify any other location of your license file directly on the generator or template designer command line using the -license option.

Running on Windows

Here is a quick instruction how to run FlexDoc/XML+OxygenXML on Windows (without much investigation):

Download the FlexDoc/XML archive and unpack it.
You will get some directory: {flexdoc-xml}
Save the flexdoc-xml.license file (containing the “OxygenXML Integration” license) in the directory:
{flexdoc-xml}\lib

Now, go to the directory:

{flexdoc-xml}\integrations\OxygenXML

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

::----------------------------------------------------------------------
:: Specify the location of JRE/JDK 9 (or later) here
::----------------------------------------------------------------------
set JAVA_HOME=C:\Program Files\Java\jdk-14

::----------------------------------------------------------------------
:: Specify the location of OxygenXML home directory
::----------------------------------------------------------------------
set OXYGENXML_HOME=C:\Program Files\Oxygen XML Editor 22

Run the generator.bat. The Generator Dialog should appear:

Now, you can test the generation of XML schema documentation with OxygenXML diagrams included.
Check that everything is specified as shown on the screenshot. Then, click the <Run> button. When the generation finishes, the result documentation should be open automatically in the default HTML browser.

Running on macOS

Download the FlexDoc/XML archive and unpack at some location (e.g. on Desktop).
You will get some directory: {flexdoc-xml}
Save the flexdoc-xml.license file (containing the “OxygenXML Integration” license) in the directory:
{flexdoc-xml}/lib
Go to the directory (open it with the Finder):
{flexdoc-xml}/integrations/OxygenXML/macOS
Edit generator.command found in that directory to specify the location of OxygenXML installation directory:
```
OXYGENXML_HOME="/Users/Shared/Oxygen XML Editor"
```
To be able to run generator.command, first you need to assign it with the executable privilege as follows:
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.
Run the generator.command. The Generator Dialog should appear:

Now, you can test the generation of XML schema documentation with OxygenXML diagrams included.

Running on Linux

Download the FlexDoc/XML archive and unpack it.
You will get some directory: {flexdoc-xml}
Save the flexdoc-xml.license file (containing the “OxygenXML Integration” license) in the directory:
{flexdoc-xml}/lib

Now, go to the directory:

{flexdoc-xml}/integrations/OxygenXML/linux

Edit generator.sh found in that directory, in these lines:

#!/bin/sh

#----------------------------------------------------------------------
# Specify the location of JRE/JDK 9 (or later) here
#----------------------------------------------------------------------
JAVA_HOME="/home/user/jdk-14"

#----------------------------------------------------------------------
# Specify the location of OxygenXML home directory
#----------------------------------------------------------------------
OXYGENXML_HOME="/home/user/Oxygen XML Editor 22"

Then, specify a permission to allow executing it as a program.

Run the generator.sh. The Generator Dialog should appear:

Now, you can test the generation of XML schema documentation with OxygenXML diagrams included.
Check that everything (i.e. the main template and the XML file) is specified similar as shown on the screenshot. Then, click the <Run> button. When the generation finishes, the result documentation should be open automatically in the default HTML browser (if not, you can find it in the output directory).

3. Settings Detail

This section describes all primary settings that are required (or may be needed) to setup and run the OxygenXML Integration. Once you know those settings, you will be able to configure the combined FlexDoc/XML+OxygenXML documentation generator for any particular environment you need (for examples, see Generator Setups).

OxygenXML Integration Plugin

OxygenXML Integration 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-oxygenxml.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+OxygenXML.

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

OS command to run OxygenXML's own DocGen

This setting specifies how to call from Java the OxygenXML's own XML schema documentation generator.

The integration works by calling OxygenXML's own documentation generator for the specified XML schemas, by which it generates the XSD diagrams along with some intermediate XML file (containing all the data, image references and hypertext image maps) supposed for further processing. That XML file is analyzed so as to associate the diagram images (and image map links) with particular DSM elements representing XML schema components in templates. That makes the diagrams and their hyperlinks available through Image Control (as “element images”) to be inserted in the output documentation generated by FlexDoc/XML.

That generator is launched on Windows by:

{OxygenXML Home}\schemaDocumentation.bat

and on Linux by:

{OxygenXML Home}/schemaDocumentation.sh

Both are command/script files, which cannot be executed directly. Rather, they must be run by an interpreter:

cmd.exe on Windows
sh on Linux

So, the command file pathname must be passed to the interpreter as an argument.

On Windows, the whole command launching the OxygenXML's own doc-generator will look like this:

cmd.exe /C "C:\Program Files\Oxygen XML Editor 22\schemaDocumentation.bat"

On Linux, the same will be:

sh "/home/user/Oxygen XML Editor 22/schemaDocumentation.sh"

The double quotes enclosing the pathname are necessary because it contain spaces.

Such a command must be passed to the OxygenXML Integration on the Java command-line that runs FlexDoc/XML. It is done using -m option. Here is the Windows variant:

-m:OXYGENXML_COMMAND="cmd.exe /C \"C:\Program Files\Oxygen XML Editor 22\schemaDocumentation.bat\""

Notice that the passed command is again enclosed in double quotes because it contains spaces, and the double quotes within it must be escaped using slash ('\').

On Linux, the same will look like this:

-m:OXYGENXML_COMMAND="sh \"/home/user/Oxygen XML Editor 22/schemaDocumentation.sh\""

Related Template Parameters

Besides the Java command-line settings required to setup the integration as a whole, there are other integration settings relevant only to a particular documentation generator (implemented as a template set). Those settings are exposed as template parameters. See:

FlexDoc/XML | XSDDoc | Parameters | Diagramming | OxygenXML Integration

4. Generator Setups

This section provides full examples of how to setup a combined FlexDoc/XML+OxygenXML documentation generator 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 OxygenXML Integration):

xsddoc.bat

set FDH=C:\flexdoc-xml

set

MODULE_PATH= %FDH%\lib\flexdoc-xml.jar;%FDH%\lib\flexdoc-xml-oxygenxml.jar;%FDH%\lib\xercesImpl.jar

set OXYGENXML_HOME=C:\Program Files\Oxygen XML Editor 22

java -Xmx1024m --module-path "%MODULE_PATH%" --module flexdoc.xml/xyz.flexdoc.xml.Generator -m:IMAGE_PROVIDER=OxygenXML -m:OXYGENXML_COMMAND="cmd.exe /C \"%OXYGENXML_HOME%\schemaDocumentation.bat\"" -template %FDH%\templates\XSDDoc\FramedDoc.tpl -format HTML -d %FDH%\out -nodialog -launchviewer=false http://www.w3.org/2001/XMLSchema.xsd

macOS Shell Script File

The same task on macOS.

The following shell script file will 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

xsddoc.command


#!/bin/sh



# FlexDoc/XML home directory

FDH='/home/user/flexdoc-xml'



# FlexDoc/XML module path

MODULE_PATH="$FDH/lib/flexdoc-xml.jar:$FDH/lib/flexdoc-xml-oxygenxml.jar:$FDH/lib/xercesImpl.jar"



# OxygenXML home directory

OXH='/Users/Shared/Oxygen XML Editor'




#-------------------------------------------------------------------------------------

# Run FlexDoc/XML generator to document an XML schema (specified in the last argument)

#-------------------------------------------------------------------------------------




  java 
  -Xmx1024m | 
  # maximum heap size allocated by JVM


   
  --module-path "$MODULE_PATH" | 
  # module path


   
  --module flexdoc.xml/xyz.flexdoc.xml.Generator | 
  # FlexDoc/XML generator's module / main class


   
  -m:IMAGE_PROVIDER=OxygenXML | 
  # OxygenXML Integration to be Element Image Provider


   
  -m:OXYGENXML_COMMAND="sh \"$OXH/schemaDocumentationMac.sh\"" | 
  # command to run OxygenXML's own xsddoc


   
  -flexdocconfig "$FDH/macOS/flexdoc.config | 
  # FlexDoc main config file prepared for macOS


   
  -template "$FDH/templates/XSDDoc/FramedDoc.tpl" | 
  # main template


   
  -format HTML -d "$FDH/out" -nodialog -launchviewer=false | 
  # output format, output directory etc.


   
  http://www.w3.org/2001/XMLSchema.xsd 
  # XML schema to document

Linux Bash File

The same task on Linux.

xsddoc.sh


#!/bin/sh



# FlexDoc/XML home directory

FDH='/home/user/flexdoc-xml'



# FlexDoc/XML module path

MODULE_PATH="$FDH/lib/flexdoc-xml.jar:$FDH/lib/flexdoc-xml-oxygenxml.jar:$FDH/lib/xercesImpl.jar"



# OxygenXML home directory

OXH='/home/user/Oxygen XML Editor 22'




#-------------------------------------------------------------------------------------

# Run FlexDoc/XML generator to document an XML schema (specified in the last argument)

#-------------------------------------------------------------------------------------




  java 
  -Xmx1024m | 
  # maximum heap size allocated by JVM


   
  --module-path "$MODULE_PATH" | 
  # module path


   
  --module flexdoc.xml/xyz.flexdoc.xml.Generator | 
  # FlexDoc/XML generator's module / main class


   
  -m:IMAGE_PROVIDER=OxygenXML | 
  # OxygenXML Integration to be Element Image Provider 


   
  -m:OXYGENXML_COMMAND="sh \"$OXH/schemaDocumentation.sh\"" | 
  # command to run OxygenXML's own xsddoc


   
  -flexdocconfig "$FDH/linux/flexdoc.config | 
  # FlexDoc main config file prepared for Linux


   
  -template "$FDH/templates/XSDDoc/FramedDoc.tpl" | 
  # main template


   
  -format HTML -d "$FDH/out" -nodialog -launchviewer=false | 
  # output format, output directory etc.


   
  http://www.w3.org/2001/XMLSchema.xsd 
  # XML schema to document

Running with Apache Ant

You can easily integrate FlexDoc/XML+OxygenXML 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"?>

</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 a framed HTML XML schema documentation by the XML schema located at http://www.w3.org/2001/XMLSchema.xsd using FlexDoc/XML | XSDDoc | FramedDoc.tpl + OxygenXML Integration, so that the result doc would appear on the “Project Reports” page of a Maven-generated project site.

pom.xml

...

<FDH>C:\flexdoc-xml</FDH>

<OXYGENXML_HOME>C:\Program Files\Oxygen XML Editor 22</OXYGENXML_HOME>

</properties>

...

<groupId>flexdoc</groupId>

<artifactId>flexdoc-xml-maven-plugin</artifactId>

<param>-m:IMAGE_PROVIDER=OxygenXML</param>

<param>-m:IMAGE_PROVIDER_CLASSPATH=${FDH}\lib\flexdoc-xml-oxygenxml.jar</param>

<param>-m:OXYGENXML_COMMAND=cmd.exe /C "${OXYGENXML_HOME}\schemaDocumentation.bat"</param>

<param>-template</param>

<param>${FDH}\templates\XSDDoc\FramedDoc.tpl</param>

<param>-p:docTitle</param>

<param>XML Schema for XML Schemas</param>

<param>-format</param>

<param>-nodialog</param>

<param>-quiet</param>

<param>http://www.w3.org/2001/XMLSchema.xsd</param>

</generatorParams>

<outputFolder>xsddoc</outputFolder>

<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=-Xms512m -Xmx1024m
call %M2_HOME%\bin\mvn.bat site:site

Note that it should be started from the directory containing the Maven pom.xml file!

Using XML Catalog

Some XML schemas may import or include other XML schemas, at that provide as a reference only the imported namespace URI, e.g.:

<import namespace="http://schemas.xmlsoap.org/wsdl/"/>

or the schema location may be specified with an opaque URI, e.g.:

<xs:include schemaLocation="urn:oasis:names:tc:dita:xsd:glossaryGrp.xsd:1.1"/>

Processing of such imports/includes without additional information about physical schema locations is impossible. Yet, to generate a proper XML schema documentation, all referenced schema must be loaded and processed!

XML catalogs can help to resolve physical locations of XML schema files. They redirect abstract URIs to physical URLs. For more details about XML catalogs, please read: FlexDoc/XML | Documentation | Installation / Configuration Files | XML Catalogs.

Both FlexDoc/XML and Oxygen XML can use XML catalogs.

Example

As an example, let's see how to generate an XML schema documentation (with all OxygenXML-generated diagrams) for the XML schemas for WSDL 1.1:


http://schemas.xmlsoap.org/wsdl/

http://schemas.xmlsoap.org/wsdl/soap/

http://schemas.xmlsoap.org/wsdl/soap12/wsdl11soap12.xsd

http://schemas.xmlsoap.org/wsdl/http/

http://schemas.xmlsoap.org/wsdl/mime/

These are the URLs, by which those schemas are located physically. At the same time, they serve as the target namespace URIs of the respective schemas (except http://schemas.xmlsoap.org/wsdl/soap12/wsdl11soap12.xsd).

The XML schema:

http://schemas.xmlsoap.org/wsdl/

is imported by all other schemas, however always with the same <xs:import> element:

<xs:import namespace="http://schemas.xmlsoap.org/wsdl/"/>

which specifies only imported namespace URI, but no schema location.

That is not enough for Oxygen XML to process such an import (even though the schema file is located by the same URL as the target namespace URI). But, the problem can be fixed with the following XML catalog file:

catalog.xml

<?xml version="1.0"?>

</catalog>

When that catalog.xml file has been specified in OxygenXML as shown on this screenshot:

Setting an XML catalog in OxygenXML

we were able to generate this documentation (click on the screenshot):

You can download this demo documentation by the link: wsdl11-xsddoc.zip (1.1 MB)

FlexDoc/XML also allows settings XML catalogs. See: FlexDoc/XML | Documentation | Running Generator | Generator GUI | Assigning XML Catalog(s).

In this particular case it wasn't needed because XSDDoc is programmed to check automatically if a namespace URI points to the physical schema. But, for instance, to generate XML Schemas for DITA 1.1, setting the XML catalog (http://docs.oasis-open.org/dita/v1.1/OS/schema/catalog.xml) will be required for both OxygenXML and FlexDoc/XML.