Table of Contents
The ILCD SDK package includes tools based on Apache Ant that are useful for several common and repetitive tasks such as validation of datasets or transformation to HTML. This document describes how to use them.
In order to use these tools, you will need Java and Apache Ant installed on your system. If you don't already have it, see the Ant Howto document for instructions.
In general, Ant is run from the command line. The basic usage pattern is
ant [options] [target [target2 [target3] ...]] [options]
A target is a set of operations that are carried out on a certain set of datasets. A list of possible target is given below.
Most of the time you will want to operate on a certain folder. All targets supplied with the SDK support the property source.dir
that can be used to point
to the folder that you want to work with. For passing the property to Ant, the -D
option is used. Thus, an example call in order to validate datasets residing
in the folder myFolder would look like this:
ant validate -Dsource.dir=myFolder
If source.dir
is omitted, it defaults to the folder sample_data
supplied with the SDK. Thus, calling
ant validate
will simply validate the datasets in sample_data
.
In general, a call to Ant can have two outcomes: success and failure. This is indicated by messages that will be written to the console after completing each run, namely BUILD SUCCESSFUL or BUILD FAILED, respectively. While the first one usually indicates that everything went well, the latter always means that there was an error during execution. If, for instance, validation errors occur when validating datasets, this will result in a failure being reported at the end of the operation.
If a message saying Warning: XML resolver not found; external catalogs will be ignored
is displayed, follow the instructions in the XML catalog section at the end of this document.
If an operation fails with an error message like java.lang.OutOfMemoryError: Java heap space
, this means that more memory has to be allocated in order to
successfully complete the operation. This can be achieved by setting the ANT_OPTS
environment variable, for instance by issuing the command (on Windows
systems)
set ANT_OPTS=-Xmx512M
,
or on *nix systems
export ANT_OPTS=-Xmx512M
(that would set the heap size to be 512MB).
The SDK package ships with an XML catalog that can be used to resolve remote XML Schema components to a locally cached copy instead. This should work automatically out of the box, however, in some cases it may not. If you are experiencing the latter, please refer to the corresponding section at the end of this document.
Ant target: validate
For technical reasons, validation requires two passes: one to ensure the XML datasets conform to the ILCD XML Schema documents and another one (referred to as ILCD Validation) to check whether they meet certain criteria that cannot be modelled with XML Schema and thus require another checking approach (which is an XSL transformation).
NOTE: A dataset is only considered valid if it successfully passes BOTH validation tests.
This operation will run both tests sequentially (by calling the following two targets), the XML Schema validation being the first.
Note: The validation will only work if the datasets are wired correctly to the schemas, i.e. the (usually relative) references to the schemas inside the datasets can actually be resolved. If operating on datasets in a location different from the ILCD SDK root directory, the schemas folder has to be copied there for validation to work, or - which is discouraged - the references to the schemas have to be altered accordingly to point to the correct schema location.
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to validate. | folder sample_data
| No |
Ant target: schemavalidate
Validate the given datasets against the ILCD XML Schema documents. This will be the first operation that is performed when calling the validate
target. Any
errors that are detected are reported to the console and the file schemavalidate.log
and the build will fail in this case.
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to validate. | folder sample_data
| No |
Example: ant schemavalidate
Ant target: ilcdvalidate
Validate the datasets against the ILCD validation XSLT stylesheet. This will be performed after successful XML Schema validation when calling the validate
target. Any errors that are detected are reported to the console and the file ilcdvalidate.log
and the build will fail in this case.
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to validate. | folder sample_data
| No |
Ant target: ilcdcompliance
Validate the datasets against the ILCD Compliance rules. Any errors that are detected are reported to the console and the file ilcdcompliance.log
and the
build will fail in this case.
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to validate. | folder sample_data
| No |
Ant target: migrate_1.1
Migrate datasets from ELCD Format 1.0.1 syntax to ILCD 1.1 syntax. This will consider all the changes to the format. See the CHANGES document for a complete list. In addition, please note the following when migrating datasets:
Some values will have to be changed or even removed during migration. In this case a notice will be issued on the console.
Some elements will change to multi-language mode. As the migration stylesheet does not know which one to use, it will default to en
. This can be
overridden by adding -DtargetLanguage=yourLang
to the command line when using the Ant-based migration or by passing the targetLanguage
parameter
to the XSLT stylesheet when performing the transformation.
If multiple telephone and/or fax numbers have been specified inside a contact dataset, only the first entry of each will be transferred to the 1.1 instance. The migration stylesheet will issue a warning for each entry not transferred.
ComplianceValues
(previously consistencyAndConformityValues
): all values of "Sufficiently conform"
will be changed to
"Not compliant"
. The migration stylesheet will issue a warning for each of those.
References to the 1.0.1 version of the ELCD format will be substituted by a reference to the ILCD Format 1.1. The same applies for references to the ELCD Conformity
System (replaced by references to ILCD Compliance System). NOTE: The source datasets "ILCD Format" and "ILCD Compliance" that are residing in the
samples
folder of this package (as well as any linked datasets and/or external documents) will be copied to the target folder and wired accordingly to
the migrated datasets. While any references to "ELCD format 1.0.1" etc. source dataset files will be replaced , the dataset files will have to be removed manually .
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to generate HTML from. | folder sample_data
| No |
target.dir
| The folder the result will be written to. | folder migrated_1.1 in current directory | No |
overwrite.existing
| If true , the output directory will be overwritten in case it already exists. |
false
| No |
replace
| If true , the folder specified as source.dir will be overwritten with the result. |
false
| No |
keepold
| If true , keep a copy of the source documents as folder previous_1.0.1 (applies only when replace is set to
true ). |
true
| No |
targetLanguage
| Set the target language for content whose parent element changed to be multilanguage. |
en
| No |
Example:
To migrate ELCD 1.0.1 dasets in the folder D:\data\ELCD_Data
, you would - assuming the current folder is the one with the ILCD SDK - first issue the
command
ant migrate_1.1 -Dsource.dir=D:\data\ELCD_Data
.
This will result in a folder migrated_1.1 to be created that contains the migrated files. To check whether they are valid against the ILCD 1.1 Format definitions, you could now enter
ant validate -Dsource.dir=migrated_1.1
.
Ant target: makehtml
Transform the XML datasets in the specified folder to an HTML representation. The references, if local, will be changed to point to the HTML equivalent (.xml filename
extensions will be translated to .html, except on permanentDataSetURI
element).
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to generate HTML from. | folder sample_data
| No |
target.dir
| The folder the result will be written to. | folder html in current directory | No |
Ant target: checkreferences
Check the references in a set of datasets for whether they can be resolved to a valid dataset. This is useful for instance prior to releasing bundles of datasets for exchange to ensure there are no dead links.
Parameters:
Option | Description | Default | Required |
---|---|---|---|
source.dir
| The folder containing the datasets to generate HTML from. | folder sample_data
| No |
checkReferences
| If true , perform reference check on elements of type GlobalReferenceType . |
true
| No |
checkPermanentDataSetURI
| If true , perform reference check on permanentDataSetURI element. |
false
| No |
localOnly
| If true , do not try to check any references pointing to a remote location (i.e. those starting with http://), but only local ones. |
false
| No |
The ILCD schemas use an external XML Schema document from W3C, xml.xsd
, which resides on the Internet at http://www.w3.org/2005/08/xml.xsd
.
That means that for validation of instance documents, be it via Ant or your own XML editor, a network connection has to be established. To circumvent this, it is possible
to instruct these tools to use a locally cached copy of xml.xsd
instead.
This package ships with an XML catalog that will allow Ant or your favorite XML editor to use this locally cached copy. The catalog is located in the tools
directory and it's called ILCD_catalog.xml
.
For using this mechanism with Ant (e.g. validating XML instances using the supplied Ant buildfile) you can choose one out of the following two options:
- Set your local CLASSPATH environment variable to include resolver.jar
(recommended).
Windows example: SET CLASSPATH=%CLASSPATH%;<ILCD-base-dir>\tools\ext\lib\resolver.jar
Mac, *nix example: export CLASSPATH=$CLASSPATH:<ILCD-base-dir>/tools/ext/lib/resolver.jar
- Pass the option "-lib tools/ext/lib/resolver.jar" to Ant every time when calling tasks that include schema validation.
If Ant can't find resolver.jar
, it will issue a warning saying "Warning: catalogpath listing external catalogs will be ignored" and then try to establish a
network connection. NOTICE THAT IF YOU'RE NEITHER USING THE XML CATALOG NOR HAVE A NETWORK CONNECTION ESTABLISHED, YOUR DOCUMENTS WILL NOT VALIDATE.
For using this catalog with your favorite XML editor, please refer to its documentation (in oXygen XML Editor, just open the settings, go to XML/XML Catalog and add
ILCD_catalog.xml
to the list).