Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
Apache Ant
Apache Maven
XMLSpy
Oxygen XML
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
JavadocPro
Examples
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 - Integrations - Apache Maven

Apache Maven Plugin

It turned out that unlike Ant, Apache Maven provides no functionality to run an external Java application directly from itself. Instead, anything you want to run from Maven needs to be wrapped as a separate Maven plugin.

Another problem is that Maven actually has (at least) two types of plugins: the normal ones and the reporting plugins. This prevents using some existing third-party plugins that do allow running external applications from Maven.

For instance, the Maven Exec Plugin found at Codehaus.org cannot be used to run DocFlex/XML Generator because it is not a reporting plugin.

So, we needed to implement our own “DocFlex/XML Maven Plugin”. This is a very simple plugin. Basically, it does little more than it calls the DocFlex/XML Generator's main class and passes to it the array of the same arguments as on the 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.

Installation

The DocFlex/XML Maven Plugin's Java source, which consists of only 'DocFlexXMLMojo.java' class, is contained in the 'integrations/maven/plugin/src/' directory included in DocFlex/XML archive.

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

  1. Edit integrations/maven/plugin/pom.xml to specify the absolute pathname of docflex-xml.jar according to your DocFlex/XML installation in the following lines:
    <dependency>
      <groupId>docflex</groupId>
      <artifactId>docflex-xml</artifactId>
      <version>1.9.5</version>
      <scope>system</scope>
      <systemPath>C:\docflex-xml-1.9.5\lib\docflex-xml.jar</systemPath>
    </dependency>
    
  2. Edit 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 DocFlex/XML Maven Plugin will be compiled and installed.

    Note: If you have no full JDK on your system, but only JRE, the pre-compiled DocFlexXMLMojo.class provided in the 'integrations/maven/plugin/target/' directory allows you to build and install the plugin anyway.

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

Usage

The DocFlex/XML Maven Plugin processes only three parameters:
<generatorParams>
The array of all command-line arguments passed to the DocFlex/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 DocFlex/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 DocFlex/XML Generator (via -d option).

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

The plugin will pass the specified value directly to DocFlex/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 DocFlex/XML Maven Plugin provides only one goal 'generator', which launches the DocFlex/XML Generator.

Since DocFlex/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=-Xms256m -Xmx512m
In a Linux shell script file, the same should be specified as the following:
export MAVEN_OPTS="-Xms256m -Xmx512m"
The lack of memory may cause the DocFlex/XML Generator to slow down very much (especially, when processing a big template application like XSDDoc) and lead eventually to java.lang.OutOfMemoryError exception!

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

Example 1

This example shows how to configure the DocFlex/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 DocFlex/XML Maven plugin -->
<plugin>
<groupId>docflex</groupId>
<artifactId>docflex-xml-maven-plugin</artifactId>
<version>1.0</version>
<configuration>
<!-- Specifying command-line parameters for DocFlex/XML Generator -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>C:/docflex-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 DocFlex/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 DocFlex/XML archive prepared for downloads.

Example 2

In this example we show how to configure the DocFlex/XML Maven Plugin to generate with it simultaneously two reports:
  1. The “Sales Report”, which is described in DocFlex/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>
<!-- DocFlex/XML home directory -->
<DFH>C:/docflex-xml</DFH>
...
</properties>
...
<!--
Reporting section (where all reports for "Project Reports" page are specified)
-->
<reporting>
<plugins>
<!-- Configure DocFlex/XML Maven plugin -->
<plugin>
<groupId>docflex</groupId>
<artifactId>docflex-xml-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 DocFlex/XML Generator -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>${DFH}/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>${DFH}/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 DocFlex/XML
Generator (via -d option).
-->
<outputFolder>sales</outputFolder>
<!--
Specify the name of the main output file.
The plugin will pass it directly to DocFlex/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 DocFlex/XML Generator's command-line parameters -->
<generatorParams>
<!-- The main template -->
<param>-template</param>
<param>${DFH}/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>${DFH}/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 DocFlex/XML archive prepared for downloads.

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.