FlexDoc/XML - Maven Integration

FlexDoc/XML Maven Plugin

This is a very simple plugin. Basically, it does little more than calling the FlexDoc/XML Generator's main class and passing to it an array of the same arguments as in the case of Java command-line.

However, our plugin both extends org.apache.maven.plugin.AbstractMojo class and implements org.apache.maven.reporting.MavenReport interface. So, it can be used both as a normal and reporting plugin simultaneously.

Note also, that although it is a simple Maven plugin, at the same time, it is a very powerful one because it does all FlexDoc/XML Generator can do. In particular:

Everything will work on any platform, where Java 11 (or later) works!

Installation

The Java source of FlexDoc/XML Maven Plugin consists of only 'FlexDocXMLMojo.java' class found at:
{flexdoc-xml}/integrations/maven/plugin/src/
where '{flexdoc-xml}' designates FlexDoc/XML installation directory.

To install the plugin into Maven repository, please follow these steps:

  1. Since FlexDoc/XML Maven Plugin stores no FlexDoc/XML Java libraries in the Maven repository, it uses everything directly from the FlexDoc/XML installation whose location must be provided in the plugin POM file:
    {flexdoc-xml}/integrations/maven/plugin/pom.xml
    Please, edit it to specify the absolute pathname of your FlexDoc/XML installation directory in the following lines (highlighted in red): 
    <properties>
  <!-- The absolute pathname of FlexDoc/XML home directory -->
  <flexdoc.xml.home>C:/flexdoc-xml-1.13</flexdoc.xml.home>
  ...
</properties>
  2. In {flexdoc-xml}/integrations/maven/plugin/ directory, depending on your OS, edit either
    install.bat / install.command / install.sh
    to specify the correct locations of your JDK and Maven installations.

    Run that command file.

    Linux

    First, you should set the «Permission» property of install.sh file to allow its execution under Linux.

    macOS

    Since macOS has extremely tight security control, to be able running install.command, you need to do the following:

    1. First, open install.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 install.command as its owner/creator, which is a precondition to be able running it!
    2. Additionally, you need to assign install.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 install.command from the Finder into the Terminal window). Then, press Enter.
    Now, you can run install.command from the Finder just by clicking twice on it.
    If everything is correct, the FlexDoc/XML Maven Plugin will be compiled and installed.
  3. To test the plugin, in the same directory depending on your OS, edit either of
    test.bat / test.command / test.sh
    according to your Java and Maven locations and run it. The generator dialog should appear.

Installation with DiagramKit

To install FlexDoc/XML Maven Plugin with the support of DiagramKit, all steps are the same as described above, but instead of you should use respectively the files:
The pom_with_DiagramKit.xml is different from pom.xml in that
See also: FlexDoc/XML | DiagramKit | FAQ | Generator Setups | Running with Apache Maven

Usage

FlexDoc/XML Maven Plugin processes only three parameters:
<generatorParams>
The array of all command-line arguments passed to the FlexDoc/XML generator (except those controlled by other two parameters).

Each command-line argument (which is either a generator option name, the option value or an input XML file) should be specified with a nested <param> element in the same order as on the FlexDoc/XML generator command-line.

<outputFolder>
Specifies the output directory name.

The plugin will convert the specified value into the absolute pathname of the output directory, which is passed further both to Maven and to FlexDoc/XML Generator (via -d option).

<outputFile>
Specifies the name of the main output file.

The plugin will pass the specified value directly to FlexDoc/XML Generator (via -f option). It will be also converted into the absolute pathname and passed to Maven (exactly that pathname will be linked from the Maven-generated “Project Reports” page).

The FlexDoc/XML Maven Plugin provides only one goal 'generator', which launches the FlexDoc/XML Generator.

Memory Heap Size

Since FlexDoc/XML Generator requires a lot of memory (especially when processing big template applications) and it will be executed by the same JVM as Maven, you need to ensure that the Maven's JVM maximum memory heap size is large enough.

You can specify this by setting 'MAVEN_OPTS' variable in a Windows command file that starts the Maven. For example:

MAVEN_OPTS=-Xms1024m -Xmx2048m
In a Linux/macOS shell script file, the same should be specified as the following:
export MAVEN_OPTS="-Xms1024m -Xmx2048m"

The lack of memory may cause the FlexDoc/XML Generator to slow down very much (especially, when processing a big template application like XSDDoc) and lead eventually to java.lang.OutOfMemoryError exception!

Example 1

This example shows how to configure the FlexDoc/XML Maven Plugin in a project POM file so as to generate using XSDDoc template set the XML schema documentation by XML Schemas for WSDL 1.1 that would appear on the “Project Reports” page of a Maven-generated project site.

pom.xml

<project>
...
<!--
Reporting section.
All reports for "Project Reports" page of the Maven-generated site should be specified here.
-->
<reporting>
<plugins>
<!-- Configure FlexDoc/XML Maven plugin -->
<plugin>
<groupId>xyz.flexdoc.xml</groupId>
<artifactId>maven-plugin</artifactId>
<version>1.0</version>
<configuration>
<!-- Specifying command-line parameters for FlexDoc/XML Generator -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>C:/flexdoc-xml/templates/XSDDoc/FramedDoc.tpl</param>
<!-- Pass template parameter -->
<param>-p:docTitle</param>
<param>XML Schemas for WSDL 1.1</param>
<!-- Specify the output format -->
<param>-format</param>
<param>HTML</param>
<!-- Suppress showing up the generator GUI -->
<param>-nodialog</param>
<!-- Suppress most of the generator messages -->
<param>-quiet</param>
<!--
Specifying the data source XML files to be processed.
The following files will be loaded directly from Internet by the given URLs.
-->
<param>http://schemas.xmlsoap.org/wsdl/</param>
<param>http://schemas.xmlsoap.org/wsdl/soap/</param>
<param>http://schemas.xmlsoap.org/wsdl/http/</param>
<param>http://schemas.xmlsoap.org/wsdl/mime/</param>
</generatorParams>
<!--
Specify the output directory name.
The plugin will convert it into the absolute pathname of the output directory,
which is passed further both to Maven and to FlexDoc/XML Generator (via -d option).
-->
<outputFolder>xsddoc</outputFolder>
<!-- For the Maven project-reports page -->
<name>XSDDoc</name>
<description>XML Schemas for WSDL 1.1</description>
</configuration>
</plugin>
</plugins>
</reporting>
...
</project>

This complete working example is included in FlexDoc/XML archive prepared for downloads.

Example 2

In this example we show how to configure the FlexDoc/XML Maven Plugin to generate with it simultaneously two reports:
  1. The “Sales Report”, which is described in FlexDoc/XML | Samples | Sales Report.
  2. The XML schema documentation (using XSDDoc templates) for the XML schema sales.xsd that describes the structure of sales.xml, the data source file for the first report.
Both reports would be placed on the “Project Reports” page of a Maven-generated project site.

pom.xml

<project>
...
<!-- Specifying properties (i.e. variables for further usage) -->
<properties>
<!-- FlexDoc/XML home directory -->
<FDH>C:/flexdoc-xml</FDH>
...
</properties>
...
<!--
Reporting section (where all reports for "Project Reports" page are specified)
-->
<reporting>
<plugins>
<!-- Configure FlexDoc/XML Maven plugin -->
<plugin>
<groupId>xyz.flexdoc.xml</groupId>
<artifactId>maven-plugin</artifactId>
<version>1.0</version>
<!-- The plugin will generate two reports -->
<reportSets>
<!--
Specifying the FIRST REPORT: "Sales Report".
(The name of the <reportSet> element is actualy misleading here.
Only one report we can define within this element.)
-->
<reportSet>
<!--
The <id> element must be always specified and unique!
Otherwise, only one report will be generated by the plugin.
-->
<id>report</id>
<configuration>
<!-- Specifying command-line parameters for FlexDoc/XML Generator -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>${FDH}/samples/sales/sales.tpl</param>
<!-- The output format -->
<param>-format</param>
<param>HTML</param>
<!-- Suppress showing up the generator GUI -->
<param>-nodialog</param>
<!-- Suppress most of generator's messages -->
<param>-quiet</param>
<!-- The input XML file with the report's data -->
<param>${FDH}/samples/sales/sales.xml</param>
</generatorParams>
<!--
Specify the output directory name.
The plugin will convert it into the absolute pathname of the report's
output directory, which will be passed both to Maven and to FlexDoc/XML
Generator (via -d option).
-->
<outputFolder>sales</outputFolder>
<!--
Specify the name of the main output file.
The plugin will pass it directly to FlexDoc/XML Generator (via -f option).
It will be also converted into the absolute pathname and passed to Maven
(exactly that pathname will be linked from the project-reports page).
-->
<outputFile>report</outputFile>
<!-- For the project-reports page -->
<name>Sales Report</name>
<description>The sales report generated from sales.xml</description>
</configuration>
<!--
Specifying the plugin's goal.
(It is necessary here. Otherwise, nothing will be generated.)
-->
<reports>
<report>generator</report>
</reports>
</reportSet>
<!--
Now, we specify the generation of the SECOND REPORT.
This will be the XSDDoc (XML schema documentation) generated for the XML schema
that describes the 'sales.xml' file used in the first report. (The 'sales.tpl'
template, which actually generates the first report, is based on that schema.)
-->
<reportSet>
<!-- The <id> is required and must be unique for each <reportSet> -->
<id>xsddoc</id>
<configuration>
<!-- The FlexDoc/XML Generator's command-line parameters -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>${FDH}/templates/XSDDoc/FramedDoc.tpl</param>
<!-- Pass template parameter: the documentation title -->
<param>-p:docTitle</param>
<param>Sales XML Schema</param>
<!-- Specify the output format -->
<param>-format</param>
<param>HTML</param>
<!-- Show no generator GUI and few messages -->
<param>-nodialog</param>
<param>-quiet</param>
<!--
The input XML file to process (i.e. the XML schema to be documented)
-->
<param>${FDH}/samples/sales/sales.xsd</param>
</generatorParams>
<!-- Specifying the report's output directory and file -->
<outputFolder>sales</outputFolder>
<outputFile>xsddoc</outputFile>
<!-- For the project-reports page -->
<name>Sales XSDDoc</name>
<description>XML schema for sales.xml</description>
</configuration>
<!-- Specifying the required plugin's goal -->
<reports>
<report>generator</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
...
</project>

This complete working example is included in FlexDoc/XML archive prepared for downloads.

Copyright© 2021 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.flexdoc.xyz or e-mail to: support@flexdoc.xyz