From XML to GRP : How to from a console

We will cover in this chapter the different ways you dispose to transform your XML document to the intermediary document (GRP document) from a console.

This mode of transformation is mainly used when writing XSLT stylesheets to ensure that they are correct.

1. What is needed

To transform your XML document to a GRP document, the Transformer needs the following things :

your XML document,
the XSLT stylesheet,
and the GRP DTD or Schema.

2. Passing parameters on the command line

2.1. Description

The class to instantiate is transformer.TransformerXMLToGRP.

The list of parameters is :

Attribute name	Description	Allowed values	Default value	Mandatory
`-grp_dtd`	Specifies the GRP DTD (file name or URL).	If a file, relative or absolute path, or a URL to GRP DTD.	-	No
`-grp_dtdoutput`	In the case the GRP Doctype is a file, specifies whether, inside the GRP document, path to GRP DTD is absolute or relative.	`absolute` or `relative`.	`absolute`	No
`-grp_dtdpublicID`	In the case the GRP Doctype is a URL, specifies the public ID of the Doctype.	Any possible string for a public ID.	-	No
`-grp_schema`	Specifies the GRP Schema (file name or URL). If you don't specify a value for this parameter, and if you don't use the parameter `-grp_dtd`, it will be assumed that the file `grp.xsd` is present in the directory containing the XML document you intend to transform.	If a file, relative or absolute path, or a URL to GRP Schema.	-	No
`-grp_schemanamespace`	Specifies the GRP Schema namespace. It must be the same than the namespace specified by the Schema you use.	Any valid value for a namespace.	-	No
`-grp_schemaoutput`	In the case the GRP Schema is a file, specifies whether, inside the GRP document, path to GRP Schema is absolute or relative.	`absolute` or `relative`.	`absolute`	No
`-grp_schemaxsi`	Specifies the GRP document namespace. Generally `http://www.w3.org/2001/XMLSchema-instance`.	Any valid value for a namespace.	`http://www.w3.org/2001/XMLSchema-instance`	No
`-xml_in`	Specifies the XML document to transform.	Relative or absolute path to any XML document.	-	Yes
`-xsl`	Specifies the XSLT stylesheet that contains the rules of transformation to get the GRP document.	Relative or absolute path to any XSLT stylesheet.	-	Yes

2.2. Examples

We will transform an existing XML document shipped with TAXI : editor/XML/XML/ex1.cd.

Note : these examples make the use of DTD only.

2.2.1. Example 1

For this first example, we will use the minimum required number of parameters.

Open a console and go to directory editor/XML/XML. Type the following command :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml_in ex1.cd -xsl CDtoGRP.xsl -grp_dtd ../grp.dtd

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp has been generated in directory editor/XML/XML. It looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

2.2.2. Example 2

We will produce an absolute path for GRP DTD.

Open a console and go to directory editor/XML/XML. Type one of the following commands, both produce the same result as -grp_dtdoutput is optional (the absolute path D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml_in ex1.cd -xsl CDtoGRP.xsl -grp_dtd D:/editor/XML/grp.dtd
    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml_in ex1.cd -xsl CDtoGRP.xsl -grp_dtd D:/editor/XML/grp.dtd -grp_dtdoutput absolute

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "file:///D:/editor/XML/grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

Note : if, on the command line, you specify a relative path like ../grp.dtd for parameter -grp_dtd then, inside GRP document, the path to GRP DTD will automatically be relative.

2.2.3. Example 3

We will produce a relative path for GRP DTD.

Open a console and go to directory editor/XML/XML. Type the following command (the absolute path D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml_in ex1.cd -xsl CDtoGRP.xsl -grp_dtd D:/editor/XML/grp.dtd -grp_dtdoutput relative

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

2.2.4. Example 4

We will use a URL as Doctype for the GRP document.

Open a console and go to directory editor/XML/XML. Type the following command (URL file:///D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml_in ex1.cd -xsl CDtoGRP.xsl -grp_dtd file:///D:/editor/XML/grp.dtd -grp_dtdpublicID test

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp PUBLIC "test"
                         "file:///D:/editor/XML/grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

3. Passing parameters through an XML parameter document

3.1. Description

The class to instantiate is still transformer.TransformerXMLToGRP.

The list of parameters is very short :

Attribute name	Description	Allowed values	Default value	Mandatory
`-xml`	Specifies the XML document containing all the parameters.	Relative or absolute path to the XML document.	-	Yes

The idea is that the XML document referred by the -xml parameter contains all the parameters necessary to the process of transformation.

It is highly recommemded to use the provided DTD editor/XML/parameters.dtd to rule the syntax of the XML parameter document, although it is not an obligation.

The XML parameter document must have parameters as root tag, and must contain the following tags, in that order :

Tag name	Description	Allowed values	Default value	Mandatory
`xml_in`	Specifies the XML document to transform.	Any XML document.	-	Yes
`xsl`	Specifies the XSLT stylesheet that contains the rules of transformation to get the GRP document.	Relative or absolute path to any XSLT stylesheet.	-	Yes
`grp_dtd`	Specifies the GRP DTD (file name or URL).	If a file, relative or absolute path, or a URL to GRP DTD.	-	No
`grp_schema`	Specifies the GRP Schema (file name or URL). If you don't specify a value for this parameter, and if you don't use the parameter `-grp_dtd`, it will be assumed that the file `grp.xsd` is present in the directory containing the XML document you intend to transform.	If a file, relative or absolute path, or a URL to GRP Schema.	-	No

Some tags may have attributes :

Tag name	Attribute name	Description	Allowed values	Default value	Mandatory
`grp_dtd`	`output`	In the case the GRP Doctype is a file, specifies whether, inside the GRP document, path to GRP DTD is absolute or relative.	`absolute` or `relative`.	`absolute`	No
	`publicID`	In the case the GRP Doctype is a URL, specifies the public ID of the Doctype.	Any possible string for a public ID.	-	No
`grp_schema`	`namespace`	Specifies the GRP Schema namespace. It must be the same than the namespace specified by the Schema you use.	Any valid value for a namespace.	-	No
	`output`	In the case the GRP Doctype is a file, specifies whether, inside the GRP document, path to GRP DTD is absolute or relative.	`absolute` or `relative`.	`absolute`	No
	`xsi`	Specifies the GRP document namespace. Generally `http://www.w3.org/2001/XMLSchema-instance`.	Any valid value for a namespace.	`http://www.w3.org/2001/XMLSchema-instance`	No

3.2. Examples

We will do the same things than previously (with the parameters typed directly in the console).

3.2.1. Example 1

For this first example, we will use the minimum required number of parameters.

Save the following XML document as editor/XML/XML/parametersCD.xml :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">

    <parameters>
      <xml_in>ex1.cd</xml_in>
      <xsl>CDtoGRP.xsl</xsl>
      <grp_dtd>../grp.dtd</grp_dtd>
    </parameters>

Open a console and go to directory editor/XML/XML. Type the following command :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml parametersCD.xml

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp has been generated in directory editor/XML/XML. It looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

3.2.2. Example 2

We will produce an absolute path for GRP DTD.

Modify editor/XML/XML/parametersCD.xml (changes are in bold, the absolute path D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">

    <parameters>
      <xml_in>ex1.cd</xml_in>
      <xsl>CDtoGRP.xsl</xsl>
      <grp_dtd output="absolute">D:/editor/XML/grp.dtd</grp_dtd>
    </parameters>

In the console, type the same command used for the previous example :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml parametersCD.xml

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "file:///D:/editor/XML/grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

Note : if you specify a relative path like ../grp.dtd for tag grp_dtd, then, inside GRP document, the path to GRP DTD will automatically be relative.

3.2.3. Example 3

We will produce a relative path for GRP DTD.

Modify editor/XML/XML/parametersCD.xml (changes are in bold, the absolute path D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">

    <parameters>
      <xml_in>ex1.cd</xml_in>
      <xsl>CDtoGRP.xsl</xsl>
      <grp_dtd output="relative">D:/editor/XML/grp.dtd</grp_dtd>
    </parameters>

In the console, type the same command used for the previous example :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml parametersCD.xml

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp SYSTEM "../grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

3.2.4. Example 4

We will use a URL as Doctype for the GRP document.

Modify editor/XML/XML/parametersCD.xml (changes are in bold, the absolute path D:/editor/XML/grp.dtd is the one I have to use on my Windows machine) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">

    <parameters>
      <xml_in>ex1.cd</xml_in>
      <xsl>CDtoGRP.xsl</xsl>
      <grp_dtd publicID="test">file:///D:/editor/XML/grp.dtd</grp_dtd>
    </parameters>

In the console, type the same command used for the previous example :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml parametersCD.xml

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE grp PUBLIC "test"
                         "file:///D:/editor/XML/grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

3.3. Overriding parameters's value on command line

When using an XML parameter document to pass parameters' value to the Transformer, you can override them on the command line, or even specify some on the command line that are not in the XML parameter document.

Let's have an example. Ensure that editor/XML/XML/parametersCD.xml is like this (the absolute path D:/editor/XML/svg.dtd is the one I have to use on my Windows machine) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">

    <parameters>
      <xml_in>ex1.cd</xml_in>
      <xsl>CDtoGRP.xsl</xsl>
      <grp_dtd output="relative">D:/editor/XML/grp.dtd</grp_dtd>
    </parameters>

In the console, type the following command :

    java -cp ../../lib/taxi.jar fr.loria.taxi.transformer.TransformerXMLToGRP -xml parametersCD.xml -grp_dtdoutput absolute

You should obtain the following output :

    Applying XSL transformations to file ex1.cd
    Generating GRP file ex1.cd.grp

Document ex1.cd.grp looks like this :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE svg SYSTEM "file:///D:/editor/XML/grp.dtd">
    <grp xmlns:java="http://xml.apache.org/xslt/java">
      ...
    </grp>

In the XML parameter document, we specified a relative path for GRP DTD. We overrided this value on the command line. We can see that the path to GRP DTD is absolute.