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:

Add the required .jar files to the cocoon/WEBINF/lib directory (if not already available - see below).
Add a <map:serializer> element in the web-application's sitemap.xmap.
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:

cocoon2.1.4.jar.
avalon-framwork-4.1.4.jar.
xmlmill.jar.
excalibur-sourceresolve-1.0.2.
excalibur-pool-1.2.jar.
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.

XMLMill User Guide