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 Configuration

Introduction

XMLMill has its own configuration file. This file is mainly used for:

  • Overriding default values for the <ml:simple-page-master> attributes (margins, page-size, ...).
  • Defining the font specifications of TrueType and external Type1 fonts.
  • Defining the location of the Glyphlist files.
  • Defining the JAXP settings.
  • Defining the Digital Signature settings.
  • Define some 'legacy' settings, facilitating the upgrade to this version.
  • Define which PDF documents should be parsed (and kept into memory) as 'template'.

Location of the config.xml file

Built-in config.xml file

The xmlmill.jar file contains a default configuration file that is used if no external configuration file is defined. This allows you to embed the xmlmill.jar file in your application (if you are a reseller for example) with the correct configuration parameters, without the need to pass an external configuration file. In the jar file you will find the file in the com\xmlmill\conf\ directory, called config.xml.

External config.xml file

It is probably easier to use an external configuration file. A config.xml file is available in the conf/ directory contained the download.

  • It is allowed to rename this file if needed. The only limitations are that it must be a well-formed and valid xml file.

Passing the configuration file to XMLMill

In case the built-in config.xml file is not used but a modified one, XMLMill must know this so the correct configuration is used.

In order to do this the location of the configuration file to use must be passed to XMLMill using the Configurator.configure() method.

  • Please check the com.xmlmill.config section in the XMLMill API chapter for more information.

Content of a config.xml file

A config.dtd is available in the conf/ directory that defines the allowed elements/attributes in a config.xml file.

The configuration file has following top-level elements:

  • <pagetemplate> -- defines the default <ml:simple-page-master> attributes if these are not defined at <ml:simple-page-master> level.
  • <fonts> -- defines the characteristics of the standard, generic and the external fonts.
  • <glyphlist> -- defines the location of the default glyhplist file and the optional glyhplist file.
  • <jaxp> -- defines the JAXP settings.
  • <cryptographic-service-provider> -- defines the Digital Signature settings.
  • <legacy> -- define some 'legacy' settings, facilitating the upgrade to a later version.
  • <template> -- define which PDF documents should be parsed (and kept into memory) as 'template'.

The following sections explain these element in more detail.

Element: <pagetemplate>

The <pagetemplate> element defines the values of the attributes that are used when a document is generated without these attrbitutes defined at the <ml:simple-page-master> element (regarding the margins and page dimensions) or <ml:document> element (regarding the fonts specifications).

The default configuration file has following attribute/value pairs:

[001] 
[002]   <pagetemplate page-width="21cm" 
[003]                 page-height="29.7cm" 
[004]                 font-type="type1" 
[005]                 font-name="helvetica" 
[006]                 font-size="10pt" 
[007]                 font-style="normal" 
[008]                 font-weight="normal" 
[009]                 margin-top="2.19cm" 
[010]                 margin-right="2.19cm" 
[011]                 margin-bottom="2.19cm" 
[012]                 margin-left="2.19cm"/>
[013]           

Element: <fonts>

The fonts section describes:

  • The attributes of the standard fonts.
  • The attributes of the generic fonts.
  • The attributes of the external fonts (Type1 and TrueType fonts).

Element: <standard>

This element contains a number of <font> elements describing the attributes of each internal font.

Example:

[001] 
[002] <font font-type="type1" 
[003]       track-kerning="on" 
[004]       pair-wise-kerning="on" 
[005]       font-metrics-file="jar:com/xmlmill/resources/afm/hv______.afm"
[006]       font-program-file="jar:com/xmlmill/resources/afm/hv______.afm">
[007]       <font-info font-name="helvetica" 
[008]                  font-style="normal" 
[009]                  font-weight="normal"
[010]       />
[011] </font>                   
[012]             

The attributes are:

font-type

Describing the type of the font (should always be type1).

track-kerning

Defines if track-kerning should be 'on' or 'off'.

pair-wise-kerning

Defines if pair-wise-kerning should be 'on' or 'off'.

font-metrics-file

Describes the loction of the fontmetrics file (for type1 fonts, this is a .afm file).

font-program-file

Describes the loction of the fontprogram file (for type1 fonts, this is a .pfb or .pfa file).

load-on-startup

Defines if the fontmetrics should be loaded ('on') when the configuration file is read in order to avoid delays when generating the first document with the font or not ('off')

  • You should always reference the font-metrics-file and font-program-file using a valid URI.
  • If the font-metrics-file value and font-program-file start with the jar protocol, it is assumed that the path references a path in an existing .jar file. By default all .afm files of the built-in internal fonts are located in the xmlmill.jar file at:com/xmlmill/resources.
  • Be aware that defining the font-metrics-file value and font-program-file filenames are case-sensitive when referred to a jar: path.

Each <font> element needs to contain at least one <font-info> element describing the attributes/value pairs needed in a .mill file to select the font to use. These attributes are:

  • font-name -- The name of the font.
  • font-style -- The style of the font.
  • font-weight -- The weight of the font.
  • The font-name, font-style and font-weight should together uniquely define a font (per font-type). If not, XMLMill will not be able uniquely define the required font during transformation.

Element: <generic>

This element contains a number of <font> elements describing the attributes of each generic font.

[001] 
[002] <font font-type="type1" 
[003]       track-kerning="off" 
[004]       pair-wise-kerning="off" 
[005]       font-metrics-file="jar:com/xmlmill/resources/afm/tir_____.afm">
[006]   <font-info font-name="serif"/>
[007] </font>           
[008]             

You should always refer to the fonts defined in the <standard> section as these will always be guaranteed available to a viewer. The font-names are in lowercase.

Typically the <font-info> element only contains the font-name attribute.

Element: <external>

External fonts are type1 or truetype fonts.

The <external> element contains a number of <font> elements describing the attributes of each external font.

Following additional attributes are:

  • embed -- If the font-metrics and font-outlines should be embedded in the PDF document.
  • subset -- If the font-outlines should be subsetted in the PDF document.
  • font-index -- The location of a TrueType font in a .ttc file.

Type1 fonts

Example: Define a type1 font:

[001] 
[002] <font font-type="type1" 
[003]       embed="on" 
[004]       subset="on" 
[005]       track-kerning="on" 
[006]       pair-wise-kerning="on" 
[007]       font-metrics-file="file:/C:/XMLMill/fonts/CALIG___.AFM"
[008]       font-program-file="file:/C:/XMLMill/fonts/CALIG___.PFB">
[009]    <font-info font-name="Calig" 
[010]               font-style="normal" 
[011]               font-weight="normal"/>
[012] </font>
[013]             

TrueType fonts

Example: Define a truetype font, based on a .ttf file:

[001] 
[002] <font font-type="truetype" 
[003]       embed="on" 
[004]       subset="on" 
[005]       track-kerning="on" 
[006]       pair-wise-kerning="on" 
[007]       font-program-file="file:/C:/XMLMill250/fonts/arial.ttf">
[008]   <font-info font-name="Arial" 
[009]              font-style="normal" 
[010]              font-weight="normal"/>
[011] </font>
[012]             

Example: Define a truetype font, based on a .ttc file:

[001] 
[002] <font font-type="truetype" 
[003]       embed="on" 
[004]       subset="on" 
[005]       track-kerning="on" 
[006]       pair-wise-kerning="on" 
[007]       font-program-file="file:/C:/XMLMill250/fonts/simsun.ttc">
[008]   <font-info font-name="Arial" 
[009]              font-style="normal"
[010]              font-weight="normal"
[011]              font-index="0" />
[012] </font>
[013]             

The font-index attribute defines which font in the true-type collection will be used.

  • Note that only the font-program-file attribute is used to define a TrueType font, the font-metrics-file attribute is not used.

In order to configure XMLMill using the contents of a configuration file please visit the Class: Configurator section in the XMLMill API chapter.

Element: <glyphlist>

The glyphlist element contains the unicode-to-glyphname list. This list determines how each unicode character is mapped to a "glyph" (a graphical shape representing a character). This allows XMLMill to replace the unicode characters in a xml/xsl document by the correct characters (bytes) that are included in the PDF document.

[001] 
[002] <glyphlist 
      default="jar:com/xmlmill/resources/glyphlist/glyphlist_in_mem.txt" 
[004]            optional="jar:com/xmlmill/resources/glyphlist/glyphlist.txt"/>
[005]           

This element has two attributes:

default

Describes the location of the file containing the list of unicode-to-glyphname comparisons that are read into memory. The default list (com/xmlmill/resources/glyphlist/glyphlist_in_mem.txt) contains all the WinAnsi characters.

optional

Describes the loction of the file containing the complete list of unicode-to-glyphname comparisons. If, during the transformation process, a character is needed that is not defined in the 'default' glyphlist, the character will be read from this list.

  • You should always reference the default and optional files using a valid URI.
  • You are free to change the content of both files.
  • The default configuration will use the glyphlists defined in the xmlmill.jar file (location: com/xmlmill/resources/, but can be changed if necessary).

Element: <jaxp>

This element defines the settings used by a JAXP parser/transformer used by XMLMill.

Element: <jaxp>

The children nodes of this element define the implementation version of the JAXP specification and the actual implementation of the different JAXP factories (see below).

The <jaxp> element has following children:

[001] <jaxp>
[002]   <implementation version="..."/>
[003]   <factories> 
[004]     <saxparser-factory        implementation-class = "..."/> 
[005]     <document-builder-factory implementation-class = "..."/> 
[006]     <transformer-factory      implementation-class = "..."/> 
[007]     <schema-factory           implementation-class = "..."/> 
[008]   </factories>
[009] </jaxp>>

Element: <implementation>

This element defines the underlying JAXP implementation version. The default version is 1.2 to stay compatible with previous versions of XMLMill.

The allowed values are 1.1, 1.2 and 1.3

  • Remember that validation of the result-tree can only be done with a JAXP 1.3 implementation.

Element: <factories>

This element defines which underlying implementation to use of following factories:

  • javax.xml.parsers.SAXParserFactory
  • javax.xml.parsers.DocumentBuilderFactory
  • javax.xml.transform.TransformerFactory
  • javax.xml.validation.SchemaFactory

The <factories> element has following children:

[001] <factories> 
[002]     <saxparser-factory        implementation-class = "..."/> 
[003]     <document-builder-factory implementation-class = "..."/> 
[004]     <transformer-factory      implementation-class = "..."/> 
[005]     <schema-factory           implementation-class = "..."/> 
[006] </factories>

Element: <saxparser-factory>

This element has exactly one attribute: implementation-class defining the name of the class in the underlying implementation that will be used to create an instance of this factory.

For example: If you use JDK1.5 the SAXParser factory is implemented in following class: com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl

  • Please check your vendor's documentation regarding the exact class name to define.

Element: <document-builder-factory>

This element has exactly one attribute: implementation-class defining the name of the class in the underlying implementation that will be used to create an instance of this factory.

For example: If you use JDK1.5 the Document Builder factory is implemented in following class: com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl

  • Please check your vendor's documentation regarding the exact class name to define.

Element: <transformer-factory>

This element has exactly one attribute: implementation-class defining the name of the class in the underlying implementation that will be used to create an instance of this factory.

For example: If you use JDK1.5 the Transformer factory is implemented in following class: org.apache.xalan.processor.TransformerFactoryImpl

  • Please check your vendor's documentation regarding the exact class name to define.

Element: <schema-factory>

This element has exactly one attribute: implementation-class defining the name of the class in the underlying implementation that will be used to create an instance of this factory.

For example: If you use JDK1.5 the Transformer factory is implemented in following class: com.sun.org.apache.xerces.internal.jaxp.validation.xs.SchemaFactoryImpl

  • Please check your vendor's documentation regarding the exact class name to define.

Element: <cryptographic-service-provider>

In order to sign documents XMLMill must be configured so it knows where to get the private key and certificate to sign the document(s).

As XMLMill is Java based it needs a keystore file where the needed information can be accessed.

The configuration file is extended with the <cryptographic-service-provider> element and it child elements:

Example:

[001] 
[002]   <cryptographic-service-provider>
[003]     <keystore file="file:/C:/Data/dsa.keystore" 
[004]               storetype="jks" 
[005]               storepasswd="123456" 
[006]               service-provider-interface="sun.security.provider.Sun"  
[007]               signaturehandler="Adobe.PPKLite" >
[008]        <alias name="xmlmill"
[009]            keypasswd="123456"/>
[010]     </keystore>
[011]   </cryptographic-service-provider>
[012]  

The following sections explain the different elements.

Element: keystore

The keystore element has various attributes describing the characteristics of the keystore that is used by XMLMill to sign the generated documents.

  • Currently only one keystore can be defined in the configuration file (config.xml).

Attribute: file

Value:

<name>

Initial:

an empty name

Required:

Yes

Description:

Defines the name and location of the keystore file.

Attribute: storetype

Value:

<name>

Initial:

an empty name

Required:

Yes

Description:

Specifies the type of keystore to be used.

Attribute: storepasswd

Value:

<name>

Initial:

an empty name

Required:

Yes

Description:

The keystore's password.

Attribute: service-provider-interface

Value:

<name>

Initial:

an empty name

Required:

No

Description:

The class name of an implementation of a specific cryptographic-service-provider.

  • In case this attribute is not defined a corresponding class will be looked for using the default Java security mechanism (looking for a provider defined in the java.security file in the /jre/lib/security directory of a Java implementation).

Attribute: signaturehandler

Value:

<name>

Initial:

an empty name

Required:

Yes

Description:

The signature handler to used when generating the pdf document.

Element: alias

The alias element defines which entries in the keystore can be used for signing a document. It has following attributes:

Attribute: name

The name of the alias as defined in the keystore that can be used to sign a document.

Attribute: keypasswd

The password of an alias.

  • The name of the alias can be referenced in the <signature> element (see later).
  • In case no aliases are defined (the alias element is absent), all available aliases in the keystore can be used to sign a document.

Element: <legacy>

The legacy element contains some children that defines if XMLMill should be backwards compatible with previous versions, facilitating the upgrade to this version.

Element: <external-graphic>

This element defines whether the DPI must be taken into consideration when reading an image (if defined in the image itself).

Uptill versions prior to 3.0 XMLMill assumed the DPI of an image was always 96. As of version 3.00 the DPI, if defined in the image file, will be used.

Example:

[001] <!-- Define legacy rules for backward compatibility -->
[002] <legacy>
[003]   <external-graphic version="3.0"  readDPIfromImage="on"/>
[004] </legacy>

The attributes are:

version

Defines as of which version of XMLMill this element will be taken into account. Leave it always at 3.0

readDPIfromImage

Defines whether or not to take into consideration the DPI setting of an image, if defined in the image file. Possible values are on or off.

Element: <templates>

The templates element defines which PDF documents should be parsed as templates during the configuration process.

This will allow high volume generation of PDF documents based on these 'templates', as these templates will only be parsed once and its' content will be kept into memory, avoiding reading the template from the persistent storage over and over again.

Element: <template>

This element defines the location of the PDF document acting as template and how to treat it.

Example:

[001] <!-- Define legacy rules for backward compatibility -->
[002] <templates>
[003]   <template pdf-file="file:/usr/templates/FormFieldsEnumerator.pdf"        
          load-on-startup="on" template-in-memory="on" />
[005] </templates>

The attributes are:

pdf-file

Defines the location of the PDF document acting as 'template'.

load-on-startup

Defines whether or not to parse this template when loading the configurator. Keep this always on except if the document should not be parsed during configuration.

template-in-memory

Defines whether or not the PDF document should be kept in memory. Keeping the document in memory will avoid reading the document from persistent storage each time a new document is generated based on this template. Keep the value on except if the document is large and you do not want to keep it into memory.

  • Multiple <template> elements can be defined.
  • If load-on-startup is off, the template document will also not be kept into memory, even if template-in-memory is on.
Copyright © 2001 - 2012. All rights reserved. XMLMill and XMLMill logo are trademarks of Pecunia Data Systems, bvba.
Powered by Apache CocoonPowered by XMLMill