XMLMill - convert xml to pdf with java. Generate PDF from xml/xsl.

XMLMill User Guide

Version: 3.00 Date: January 2nd, 2008
This tutorial is opened in a separate window in order to maximize the legibility of this tutorial.
To return to XMLMill, close this browser window

This page as PDFPrinter friendly pageThis guide (!) as PDF

XMLMill Connectors

Connectors make it easy to integrate XMLMill in other applications or software environments.

Cocoon 2.1.4

The com.xmlmill.connector.cocoon.XMLMillSerializer_214 class can be used by Cocoon to generate .pdf documents in a web environment (Cocoon 2.1.4).

  • This class can only be used with Cocoon 2.1.4. If you want to use this class into an earlier version of Cocoon you need to modify the source code. The source code of this class can be found in the samples/connector/cocoon directory in the download. Do not hesitate to contact us (support@xmlmill.com) if you need any help.

In order to be able to use the XMLMillSerializer_214 class, you need to:

  1. Add the required .jar files to the cocoon/WEBINF/lib directory (if not already available - see below).
  2. Add a <map:serializer> element in the web-application's sitemap.xmap.
  3. Add a <map:match> element for the URI's you want to generate .pdf documents for.

Required .jar files (in the cocoon/WEBINF/lib)

The required .jar files (located in cocoon/WEBINF/lib) are:

  1. cocoon2.1.4.jar.
  2. avalon-framwork-4.1.4.jar.
  3. xmlmill.jar.
  4. excalibur-sourceresolve-1.0.2.
  5. excalibur-pool-1.2.jar.
  6. The .jar files representing your JAXP compliant implementation of the xml-parser and xsl-transformer.
  • Most of the .jar files will already be available in the cocoon/WEBINF/lib directory as they are part of Cocoon.

Add <map:serializer> element.

The web-application that will offer the online generation of .pdf documents should add following to its' sitemap.xmap:

[001] 
[002] <?xml version="1.0"?>
[003]   <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
[004]   <map:components>
[005]     ...
[006]     <map:serializers default="html">
[007]       <map:serializer logger="xmlmill.serializer.ml2pdf-webpages" 
[008]            mime-type="application/pdf" 
[009]         name="ml2pdf-webpages" 
              src="com.xmlmill.connector.cocoon.XMLMillSerializer">
[011]       <!-- The XMLMill configuration to use (if any) -->
[012]       <config-file/>
[013]       <!-- The log-file -->
[014]       <log-file>logs/xmlmill.log</log-file>
[015]       <!-- The log-level -->
[016]       <log-level>debug</log-level>
[017]       <!-- Should serializer set content length header or not? -->
[018]       <set-content-length>true</set-content-length>
[019]       <!-- Should WARNings lead to abortion of the generation ? -->
[020]       <abort-on-warning>true</abort-on-warning>
[021]       <!-- Should ERRORs lead to abortion of the generation ? -->
[022]       <abort-on-error>true</abort-on-error>
[023]       <!-- The systemid (needed to define relative URLs (should point to 
            the resources
[025]            used to generate the document. -->
[026]       <systemid>context://xmlmill</systemid>
[027]       </map:serializer>
[028]     </map:serializers>
[029]     ...
[030]   </map:components>
[031]   ...

When Cocoon is started these parameters are passed to the XMLMillSerializer instance using the Configure method.

Add a <map:match> element

One (or more) <map:match> elements are needed so that passed URIs can return a genereted pdf document:

[001] 
[002] <map:match pattern="*.topdf">
[003]   <!-- Generate xml document -->
[004]   <map:generate type="file" src="documents/{1}.xml"/>
[005]   <!-- Transform main document to the .mill format -->
[006]   <map:transform src="stylesheets/topdf/rnotes.xsl"/>
[007]   <!-- Serialize using the 'ml2pdf' serializer -->
[008]   <map:serialize type="ml2pdf"/>
[009] </map:match>

Ant.

As of this version XMLMill can be used with Ant in order to :

  • Generate PDF documents
  • Compare PDF documents
  • A basic knowlegde of creating build files in Ant is assumed.

Configuration

Create a classpath reference

Create a classpath reference for the XMLMill task. It must include all .jar files that XMLMill uses, including the xmlmill.jar itself. In case JSDK1.3 is used, following applies:

[001] <path id="mill-classpath">
[002]   <fileset dir="C:\Data\XMLMill\Release-to-production\_Libraries">
[003]     <include name="dom.jar"/>
[004]     <include name="jaxp-api.jar"/>
[005]     <include name="sax.jar"/>
[006]     <include name="xalan.jar"/>
[007]     <include name="xercesImpl.jar"/>
[008]     <include name="xmlmill.jar"/>
[009]     <include name="log4j-1.2.8.jar"/>
[010]     <include name="commons-logging-1.1.jar"/>    
[011]   </fileset>
[012] </path>
[013] <property name="mill.path" refid="mill-classpath"/>
  • Above example assumes JSDK 1.3 is used.

In case JSDK 1.4 or JSDK 1.5 is used following applies:

[001] <path id="mill-classpath">
[002]   <fileset dir="C:\Data\XMLMill\Release-to-production\_Libraries">
[003]     <include name="xmlmill.jar"/>
[004]     <include name="commons-logging-1.1.jar"/>    
[005]   </fileset>
[006] </path>
[007] <property name="mill.path" refid="mill-classpath"/>

Create an XMLMill task

Create an XMLMill task in your build file using the <taskdef> task:

[001] <taskdef name="mill" 
[002]          classname="com.xmlmill.connector.ant.XMLMillTask" 
[003]          classpath="${mill.path}"/> 
[004]                         

1

The public class to use is: com.xmlmill.connector.ant.XMLMillTask.

2

Refer to the mill-classpath.

Generating PDF documents

To generate PDF documents the <generate> element in the <mill> task is used:

[001] <mill maxmemory="512m" 
[002]       tempdir="c:\brol\anttest"   
[003]       printsummary="on" 
[004]       loglevel="debug">
[005]   <classpath refid="mill-classpath"/>
[006]   <!--
[007]     Generate the PDF documents 
[008]   -->
[009]   <generate name="G1"  
[010]             haltonwarning="false" 
[011]             outputfolder="C:\brol\outputtest" 
[012]             validate="on" 
[013]             todir="C:\data\generate-1.log">
[014]     <fileset dir="C:\Data\_unittests"> 
[015]                 <include name="mill/*.mill"/>
[016]     </fileset>
[017]   </generate>
[018] <mill>			
1

The attributes defined at <mill> level are automatically inherited by the descendant elements (<generate> and compare) if applicable.

2

For more information regarding the applicable attributes please consult the Parameters section.

3

Multiple <fileset> elements can be defined to determine which .mill or .xml files to handle.

  • A <mill> task can contain multiple <generate> elements.
  • The generation of PDF documents defined by each <generate> element is executed in a separate JVM environment.

Comparing PDF documents

To compare PDF documents the <compare> element in the <mill> task is used:

[001] <mill maxmemory="512m" 
[002]       tempdir="c:\brol\anttest"   
[003]       printsummary="on" 
[004]       loglevel="debug">
[005] 
[006]   <classpath refid="mill-classpath"/>
[007]   <!--
[008]     Compare the PDF documents 
[009]   -->
[010]   <compare name="C1" 
[011]            haltonerror="false" 
[012]            todir="C:\XMLMill2.60\samples\mill\log\compare-1.log" >
[013]     <master>   
[014] 	     <fileset dir="C:\Data\XMLMill\TestDirectory\_master">
[015]            <include name="mill/**/*.pdf"/>
[016]          </fileset>
[017]     </master>  
[018]     <slave dir="C:\brol\outputtest"/>
[019]   </compare>
[020] <mill>			
1

The attribute defined at <mill> level are automatically inherited by the descendant elements (<generate> and <compare>) if applicable.

2

For more information regarding the applicable attributes please consult the Parameters section.

3

The <master> element defines which PDF document should act as 'master'. These are the correct documents to be compared to. It must contain exactly 1 <fileset> element.

4

The <slave> element defines where the generated documents are stored.

  • A <mill> task can contain multiple <compare> elements.
  • The comparing of PDF documents defined by each <compare> element is executed in a separate JVM environment.

Parameters

<mill> element

  • The parameters defined at <mill> level are automatically inherited by the descendant elements (<generate> and compare) if applicable.
Attribute Description Required
append Append messages to an existing log file instead of overwriting the log file. If the log file does not exist, it is created. No; default is off.
config Defines the configuration file (config.xml)to use. If not defined, the The default configuration file in the xmlmill.jar file is used. No.
dir The directory in which to invoke the VM (if jvm attribute is used. No
haltonerror Stop the build process if an error occurs during the generation or comparing of pdf documents. No; default is off.
haltonwarning Stop the build process if a warning occurs during the generation of pdf documents. No; default is off.
jaxp Defines the JAXP version of the underlying implementation (1.1, 1.2 or 1.3). No; default 1.2.
jvm The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec(). No; default is java.
loglevel Defines the loglevel. The values can be: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. If the value passed is different than the ones defined here, the loglevel is set to DEBUG. No; default is INFO.
includeantruntime Implicitly add the Ant classes required to run the generation and competing process to the classpath. No; default is true.
maxmemory Maximum amount of memory to allocate to the forked VM. No
outputfolder Defines the outputfolder. This is where the generated PDF documents are stored. YES
printsummary Print one-line statistics. No; default is off.
size Define the minimum size (in bytes) the pdf document should be. No; default is the project's base directory.
tempdir Where temporary files should be put. During the generate and compare processes temporary files are generated concerning the selected files and attribute settings. No; default is the project's base directory.
timeout Cancel the individual generation of PDF documents if they don't finish in the given time (measured in milliseconds). No
todir Directory to write the reports to. YES
validate Validates the result tree. Note: This requires a JAXP 1.3 compliant implementation of the underlying transformer. No; default is off.
verbose Send any output generated to the console as well as to the logilfe(s). No; default is off.
xslt XSLT transformation only (transform .xml/.xsl file to a .mill file). No; default is off.

<generate> element

Attribute Description Required
append Append messages to an existing log file instead of overwriting the log file. If the log file does not exist, it is created. No; default is off.
config Defines the configuration file (config.xml)to use. If not defined, the The default configuration file in the xmlmill.jar file is used. No.
haltonerror Stop the build process if an error occurs during the generation or comparing of pdf documents. No; default is off.
jaxp Defines the JAXP version of the underlying implementation (1.1, 1.2 or 1.3). No; default 1.2.
loglevel Defines the loglevel. The values can be: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. If the value passed is different than the ones defined here, the loglevel is set to DEBUG. No; default is INFO.
name Defines the name of the <compare> element. This name is used as a reference in the log file (see the Logging section.
printsummary Print one-line statistics. No; default is off.
size Define the minimum size (in bytes) the pdf document should be. No; default is the project's base directory.
todir Directory to write the reports to. YES
validate Validates the result tree. Note: This requires a JAXP 1.3 compliant implementation of the underlying transformer. No; default is off.
verbose Send any output generated to the console as well as to the logilfe(s). No; default is off.
xsl Defines the .xsl file that will be used to transform the .xml files. If specified this .xsl file will overrule any .xsl file defined in the .xml file (defined in the <?xml-stylesheet ...?>ag). No.
xslt XSLT transformation only (transform .xml/.xsl file to a .mill file). No; default is off.

<compare> element

Attribute Description Required
append Append messages to an existing log file instead of overwriting the log file. If the log file does not exist, it is created. No; default is off.
haltonerror Stop the build process if an error occurs during the generation or comparing of pdf documents. No; default is off.
loglevel Defines the loglevel. The values can be: TRACE, DEBUG, INFO, WARN, ERROR, FATAL. If the value passed is different than the ones defined here, the loglevel is set to DEBUG. No; default is INFO.
name Defines the name of the <compare> element. This name is used as a reference in the log file (see the Logging section. No
printsummary Print one-line statistics. No; default is off.
todir Directory to write the reports to. YES
verbose Send any output generated to the console as well as to the logilfe(s). No; default is off.

Parameters as nested elements

Inside a <mill> element

<generate> element

Multiple <generate> elements can be defined inside the <mill> element.

<compare> element

Multiple <compare> elements can be defined inside the <mill> element.

<classpath>

The <mill> task supports a nested <classpath> element that represents a PATH like structure.

<jvmarg>

Additional parameters may be passed to the new VM via nested <jvmarg> elements. For example:

[001] <mill">
[002]   <jvmarg value="-Djava.compiler=NONE"/>
[003]   ...
[004] </mill>
[005]       

would run the test in a VM without JIT.

<jvmarg> allows all attributes described in Command-line Arguments.

Inside a <generate> element

<fileset> element

Multiple <fileset> elements can be defined inside the <generate> element.

Inside a <compare> element

<master> element

Exactly one <master> element can be defined inside the <compare> element.

<slave> element

Exactly one <slave> element can be defined inside the <slave> element.

Inside a <master> element

<fileset> element

Multiple <fileset> elements can be defined inside the <generate> element.

Inside a <slave> element

No sub elements.

Logging

The logging reports produced are different for the generation or comparing process:

Generation process

For each generation process 2 log files are generated:

Summary log

A summary file with an overview of the PDF documents to generate, the number of PDFs successfully generated and the number of failures, followd by a list of all failed .xml/.mill files.

The name of this summary file is the same as defined by the todir attribute of the <generate> element.

[001] 
[002] Job         :Example_volume_paragraph 
[003] Date        :Thu Jul 27 22:19:14 CEST 2006 
[004] Details     
      :E:\Data\tests\reports\details\volume-paragraph-1154031508062.log 
[006] PDFs        :3 
[007] Success     :3 
[008] Failures    :0 
[009] Time elapsed:45,719     
[010]                             

This summary files contains:

1

The name of the 'Job (this is the name of the process as defined by the name attribute of the <generate> element.

2

The date when the file was created.

3

The location of the log file containing all details of the generation process.

4

The number of PDF documents to generate.

5

The number of successfull generated PDF documents.

6

The number of failed documents.

7

The elapsed time.

Detailed log

A detailed log file containing all the logging messages of the generation process (as produced by XMLMill)

[001] 
[002] INFO  [main]: ====================================================
[003] INFO  [main]: = XMLMill build: XMLMill Java @version@
[004] INFO  [main]: = Licensed to  : XMLMill (Aartselaar - Belgium) (0000000)
[005] INFO  [main]: = ErrorLog created at: Thu Jul 27 22:18:28 CEST 2006
[006] INFO  [main]: ====================================================
[007] INFO  [main]: Current log file: 
      E:\Data\tests\reports\details\volume-paragraph-1154031508062.log
[009] INFO  [main]: Current log-level: INFO
[010] ...
[011]     

The detailed log file contains all logging messages (based on the log-level defined) of the generation process as defined by XMLMill.

Compare process

For each compare process 2 log files generated:

Summary log

A summary file with an overview of the PDF documents to compare, the number of PDFs successfully compared and the number of failures, followd by a list of all failed .pdf files.

The name of this summary file is the same as defined by the todir attribute of the <compare> element.

[001] 
[002] Job         :C1  
[003] Date        :Thu Jul 27 22:27:21 CEST 2006  
[004] Details     :E:\Data\tests\reports\details\compare-1-1154031965343.log  
[005] PDFs        :178  
[006] Success     :178  
[007] Failures    :0  
[008] Time elapsed:76,095    
[009]                             

This summary files contains:

1

The name of the 'Job (this is the name of the process as defined by the name attribute of the <generate> element.

2

The date when the file was created.

3

The location of the log file containing all details of the compare process.

4

The number of PDF documents to compare (as defined by the <master> element.

5

The number of successfull compare PDF documents.

6

The number of failed compares.

7

The elapsed time.

Detailed log

A detailed file containing all the logging messages of the compare process.

[001] 
[002] INFO  [main]: ====================================================
[003] INFO  [main]: = XMLMill build: XMLMill Java @version@
[004] INFO  [main]: = Licensed to  : XMLMill (Aartselaar - Belgium) (0000000)
[005] INFO  [main]: = ErrorLog created at: Thu Jul 27 22:26:05 CEST 2006
[006] INFO  [main]: ====================================================
[007] INFO  [main]: Current log file: 
      E:\Data\XMLMill\Release-to-production\rev2-70-65\tests\reports\details\comp
      are-1-1154031965343.log
[010] INFO  [main]: Current log-level: DEBUG
[011] INFO  [main]: Comparing... E:\Data\...\Attribute_topleft.pdf with 
      E:\Data\..output\Attribute_topleft.pdf
[013] INFO  [main]: Comparing... E:\Data\...\Attribute_text-transform.pdf with 
      E:\Data\...\Attribute_text-transform.pdf
[015] ...    
[016]     

Examples

Following example is taken out of an existing build file. During the build process PDF documents are automatically generated and compared with a 'master' directory.

[001] 
[002] <mill config="${testdirectory.dir}/config/config.xml"       
[003]       printsummary="on"
[004]       loglevel="info"
[005]       tempdir="${test.temp}" 
[006]       verbose="off"
[007]       haltonwarning="false"
[008]       maxmemory="512m"
[009]       haltonerror="no"
[010] >
[011]   <classpath>
[012]     <path refid="mill-classpath"/>                           
[013]   </classpath>        			
[014] <!--
[015] Generate the PDF documents 
[016] -->
[017] <generate name="Generic"                                     
[018]           outputfolder="${test.results}" 
[019]           validate="on" 
[020]           todir="${test.reports}/generic.txt"
[021] >
[022]   <fileset dir="${testdirectory.dir}/_unittests">         
[023]     <include name="**/*.mill"/>							
[024]     <include name="**/*.xml"/>	
[025]     <exclude name="**/volume/**"/>					       											       
[026]     <exclude name="**/nissan/**"/>
[027]     <exclude name="**/mill/Element_Signature-*.mill"/>
[028]   </fileset>			
[029] </generate>
[030] 
[031]         			
[032] <generate name="Nissan"                                      
[033]           outputfolder="${test.results}" 
[034]           validate="on" 
[035]           todir="${test.reports}/nissan.txt"
[036]           append="true"
[037]           
                xsl="${testdirectory.dir}/_unittests/customers/nissan/belspec-2.00.xsl"
[039] >
[040]   <fileset dir="${testdirectory.dir}/_unittests">             
[041]     <include name="**/nissan/*.xml"/>					       											       
[042]   </fileset>			
[043] </generate>        			
[044]         			
[045]         			
[046]  			        		
[047]         			
[048] <!--
[049] Compare the PDF documents             
[050] --> 	
[051] <compare loglevel="debug"                                         
[052]       name="C1" 
[053]       verbose="off"  
[054]       todir="${test.reports}/compare-1.txt" 
[055] >
[056]   <master>
[057]     <fileset dir="${testdirectory.dir}/_master">
[058]       <include name="**/*.pdf"/>
[059]     </fileset>
[060]   </master>
[061]   <slave dir="${test.results}"/>
[062] </compare>
[063] </mill>
1

The <mill> element defines the configuration file to use (used for generating the pdf document) and set the memory to use to 512 MB.

2

Defines the classpath (see the Create a classpath reference section for more information).

3

Define the first batch of PDF document to generate, based on the <fileset>s defined.

4

The <fileset> defines the location of the .mill or .xml files. The .xml files must include a reference to their respective .xsl files.

5

The generate element defines xml files that needs to be generated with the same .xsl file (as defined by the xsl parameter).

6

The compare element defines the location of the master pdf documents and the location of the slave PDF documents to compare with.

  • If there are more documents in the slave directory than in the master that will not be reported as an error.
  • if an .xsl file is define using the xsl parameter, it will overrule any .xls file referenced in an .xml document.
Copyright © 2001 - 2012. All rights reserved. XMLMill and XMLMill logo are trademarks of Pecunia Data Systems, bvba.
Powered by Apache CocoonPowered by XMLMill