FlexDoc/XML - Ant Integration

You can easily integrate FlexDoc/XML with the Apache Ant automated build system.

Although we do not provide currently a specific Ant plugin, actually, it is not necessary. You may equally call the FlexDoc/XML Generator from Ant simply as a Java application.

Here is an example of how it can be done.

Let's suppose, you want to generate a framed HTML documentation 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 command file that launches such a generation:

set  FDH=C:\flexdoc-xml
set  CP=%FDH%\lib\xml-apis.jar;%FDH%\lib\xercesImpl.jar;%FDH%\lib\resolver.jar;%FDH%\lib\flexdoc-xml.jar
java  -Xmx512m -cp %CP% xyz.flexdoc.xml.Generator -template %FDH%\templates\XSDDoc\FramedDoc.tpl -format HTML -d %FDH%\out -nodialog -launchviewer=false http://www.w3.org/2001/XMLSchema.xsd
The following is an equivalent Ant build.xml file doing the same:


<?xml version="1.0"?>
<project basedir="." name="FlexDoc/XML Ant Integration Demo">
<!-- This will generate an XML schema documentation -->
<target name="XSDDoc">
<!-- the location of the FlexDoc/XML home directory -->
<property name="FDH" value="C:/flexdoc-xml"/>
<!-- the FlexDoc/XML Java class path -->
<property name="CP" value="${FDH}/lib/xml-apis.jar;${FDH}/lib/xercesImpl.jar;${FDH}/lib/resolver.jar;${FDH}/lib/flexdoc-xml.jar"/>
Execute the FlexDoc/XML generator.

IMPORTANT: The 'maxmemory' attribute sets the maximum heap size
available to Java VM when running FlexDoc/XML.
Check this attribute when you need to process large quantities of data!

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 1024m, instead of 512m.

The 'fork' attribute forces Ant to launch a separate instance of JVM.
This is needed to ensure that the memory specified in the 'maxmemory'
attribute will be allocated indeed. (However, you may remain using Ant's
JVM instance, if you have already specified for it that much of memory.)
<java classname="xyz.flexdoc.xml.Generator" classpath="${CP}" fork="true" maxmemory="512m">
All options you want to pass to the FlexDoc/XML Generator should be specified
here with the <arg> elements in the same order as on the command line.
<!-- the main template -->
<arg value="-template"/>
<arg value="${FDH}/templates/XSDDoc/FramedDoc.tpl"/>
<!-- pass the template parameter 'docTitle' (the documentation title) -->
<arg value="-p:docTitle"/>
<arg value="XML Schema for XML Schemas"/>
<!-- the output format -->
<arg value="-format"/>
<arg value="HTML"/>
<!-- the output directory -->
<arg value="-d"/>
<arg value="${FDH}/out"/>
<!-- do not launch the generator GUI -->
<arg value="-nodialog"/>
<!-- do not launch the default viewer for the output file -->
<arg value="-launchviewer=false"/>
Specify one or many data source XML files to be processed
by the specified template. (Both local pathnames and URLs
are allowed.)
In this example, it is the XML schema to be documented.
<arg value="http://www.w3.org/2001/XMLSchema.xsd"/>

To run that build.xml file, you can use a Windows BAT command file specified like the following:

set ANT_HOME=C:\apache-ant
set PATH=%ANT_HOME%\bin;%PATH%
set JAVA_HOME=C:\Program Files\Java\jre8
call %ANT_HOME%\bin\ant.bat xsddoc
(Note that it should be started from the directory containing the Ant build.xml file!)