FlexDoc/XML - Maven Integration
However, our plugin both extends
class and implements
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:
- To run XSDDoc/WSDLDoc and generate your XML schema / WSDL documentation.
- To generate along that any XSD diagrams inserted automatically into the documentation. That is possible because DiagramKit, which generates those diagrams, is equally part of FlexDoc/XML.
'FlexDocXMLMojo.java'class, is contained in the
'integrations/maven/plugin/src/'directory included in FlexDoc/XML archive.
To install the plugin into Maven repository, please follow these steps:
integrations/maven/plugin/pom.xmlto specify the absolute pathname of
flexdoc-xml.jaraccording to your FlexDoc/XML installation in the following lines:
<dependency> <groupId>flexdoc</groupId> <artifactId>flexdoc-xml</artifactId> <version>1.12</version> <scope>system</scope> <systemPath>C:\flexdoc-xml-1.12.2\lib\flexdoc-xml.jar</systemPath> </dependency>
integrations/maven/plugin/install.bat(on Windows) or
integrations/maven/plugin/install.sh(on Linux) to specify the correct locations of your JDK/JRE and Maven installations.
Run this command file.
If everything is correct, the FlexDoc/XML Maven Plugin will be compiled and installed.
Note: If you have no full JDK on your system, but only JRE, the pre-compiled
FlexDocXMLMojo.classprovided in the
'integrations/maven/plugin/target/'directory allows you to build and install the plugin anyway.
To test the plugin, edit
integrations/maven/plugin/test.bat(on Windows) or
integrations/maven/plugin/test.sh(on Linux) according to your Java and Maven locations and run it. The generator dialog should appear.
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.
- 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).
- 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).
'generator', which launches the FlexDoc/XML Generator.
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:
export MAVEN_OPTS="-Xms256m -Xmx512m"
According to our tests, allowing 512 Mb heap size on 32-bit Java is OK in most cases
(e.g. running XSDDoc to document large XML schemas).
However, for 64-bit Java (running on 64-bit OS) this amount must be doubled.
So, you should specify
-Xmx1024m, instead of
All reports for "Project Reports" page of the Maven-generated site
should be specified here.
Specifying the data source XML files to be processed.
The following files will be loaded directly from Internet by the given URLs.
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).
- The “Sales Report”, which is described in FlexDoc/XML | Samples | Sales Report.
The XML schema documentation (using XSDDoc templates) for the XML schema
sales.xsdthat describes the structure of
sales.xml, the data source file for the first report.
Reporting section (where all reports for "Project Reports" page are specified)
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.)
The <id> element must be always specified and unique!
Otherwise, only one report will be generated by the plugin.
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).
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).
Specifying the plugin's goal.
(It is necessary here. Otherwise, nothing will be generated.)
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.)
The input XML file to process (i.e. the XML schema to be documented)