From XML to GRP : How to by programming

We saw in the previous chapter how to apply transformation from command line. In this chapter, we will explain how to apply transformation by programming.

1. What is needed

You still need the following things :

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

2. Example 1

2.1. First step

In this first step, we will code the example to set up the main architecture. During the second step, we will really build the list of paramaters needed by the Transformer.

2.1.1. Code

Save the following code under editor/test/XMLToGRPTest.java :

    import fr.loria.taxi.transformer.TransformerXMLToGRP;
    import fr.loria.taxi.transformer.util.XMLToGRPParameters;


    public class XMLToGRPTest {
      /**
       * This method prepares the parameters needed by the process of transformation. If any
       * error happens, we display an error message and leave the application.
       *
       * @return The list of parameters as an XMLToGRPParameters object.
       */
      public static XMLToGRPParameters getParameters() {
        XMLToGRPParameters parameters = null;

        try {
          // The array containing the parameters
          String[] args = new String[0];

          // HERE WE SHOULD FILL IN THE args ARRAY WITH THE LIST OF PARAMETERS AND THEIR VALUE

          parameters = new XMLToGRPParameters(args);
        } catch (Exception e) {
          // We report any error that might happen with the parameters and leave the application
          System.err.println("-- Something wrong with the parameters --");
          System.err.println(e.getMessage());
          System.exit(1);
        }

        return parameters;
      }


      /**
       * Main method.
       */
      public static void main(String[] args) {
        try {
          // Prepares the list of parameters
          XMLToGRPParameters parameters = getParameters();

          // Creates the Transformer and calls the process() method that operates the process
          // of transformation
          new TransformerXMLToGRP(parameters).process();
        } catch (Exception e) {
          // We report any error that might happen during the process of transformation
          System.err.println("-- Something wrong happened during the transformation --");
          System.err.println(e.getMessage());
        }
      }
    }
  

Open a console, go to directory editor/test and compile XMLToGRPTest.java with the following command :

    javac -classpath ../lib/taxi.jar XMLToGRPTest.java
  

For compiling, you must specify the jar containing the classes transformer.TransformerXMLToGRP and import fr.loria.taxi.transformer.util.XMLToGRPParameters imported at the very top of your code. These 2 classes are contained in the jar taxi.jar (in directory lib) shipped with TAXI.

Note : classes and sources are usually not saved in the same directory. This is not the case with the previous command line used for compiling. I chose to do that to focus only on the process of transformation and use the minimum number of necessary options on the command line.

2.1.2. Explaining the code

You must import 2 classes :

• transformer.TransformerXMLToGRP : the Transformer used to apply the transformation,
• transformer.util.XMLToGRPParameters : holds the parameters passed to the Transformer.

The method main(String[] args) does 2 things :

1. prepares the XMLToGRPParameters object by calling the method getParameters(),
2. instanciates the TransformerXMLToGRP (the constructor takes a XMLToGRPParameters object as parameter) and applies the tranformation by calling the method process() on that object.

A try catch block encloses this code as Exception may be thrown during the transformation.

We wrote a method called getParameters() to prepare the XMLToGRPParameters object that holds the different parameters and their respective value. In this method, we instanciate a XMLToGRPParameters object (the constructor takes an array of String objects that represents the transformation process' parameters and their value). We didn't specify yet the list of parameters in that array of String. We are going to do that in the Second step.

The creation of the XMLToGRPParameters is enclosed in a try catch block as it may throw Exception if something is wrong with the arrays of String representing the transformation process' parameters and their value. In such a case, we display an error message and stop the application.

2.1.3. Running the code

Run the example with this command (depending on the OS you run it, you will not use the same classpath separator) :

    java -classpath ../lib/taxi.jar;. XMLToGRPTest (under Windows)
    java -classpath ../lib/taxi.jar:. XMLToGRPTest (under other OS)
  

You get the following output :

    -- Something wrong with the parameters --
    Parameter 'xsl' is missing.
  

In the method getParameters(), we got an Exception because, so far, the object XMLToGRPParameters is created with an empty array. We intercepted this Exception, showed its message, and left the application.

We will now complete the previous example by adding parameters to transform an XML document shipped with TAXI : editor/XML/XML/ex1.cd.

2.2.1. Code

Modify editor/test/XMLToGRPTest.java (changes are indicated in bold) :

    import fr.loria.taxi.transformer.TransformerXMLToGRP;
    import fr.loria.taxi.transformer.util.Parameters;
    import fr.loria.taxi.transformer.util.XMLToGRPParameters;


    public class XMLToGRPTest {
      /**
       * This method prepares the parameters needed by the process of transformation. If any
       * error happens, we display an error message and leave the application.
       *
       * @return The list of parameters as an XMLToGRPParameters object.
       */
      public static XMLToGRPParameters getParameters() {
        XMLToGRPParameters parameters = null;

        try {
          // The array containing the parameters
          String[] args = new String[6];

          // XML document to transform
          args[0] = Parameters.PARAMETER_SIGN + Parameters.XML_IN;  // -xml_in
          args[1] = "../XML/XML/ex1.cd";

          // XSLT stylesheet to use
          args[2] = Parameters.PARAMETER_SIGN + Parameters.XSL;     // -xsl
          args[3] = "../XML/XML/CDtoGRP.xsl";

          // GRP DTD
          args[4] = Parameters.PARAMETER_SIGN + Parameters.GRP_DTD; // -grp_dtd
          args[5] = "../grp.dtd";

          parameters = new XMLToGRPParameters(args);
        } catch (Exception e) {
          // We report any error that might happen with the parameters and leave the application
          System.err.println("-- Something wrong with the parameters --");
          System.err.println(e.getMessage());
          System.exit(1);
        }

        return parameters;
      }


      /**
       * Main method.
       */
      public static void main(String[] args) {
        try {
          // Prepares the list of parameters
          XMLToGRPParameters parameters = getParameters();

          // Creates the Transformer and calls the process() method that operates the process
          // of transformation
          new TransformerXMLToGRP(parameters).process();
        } catch (Exception e) {
          // We report any error that might happen during the process of transformation
          System.err.println("-- Something wrong happened during the transformation --");
          System.err.println(e.getMessage());
        }
      }
    }
  

Open a console, go to directory editor/test (if not already done) and compile XMLToGRPTest.java with the following command :

    javac -classpath ../lib/taxi.jar XMLToGRPTest.java
  

2.2.2. Explaining the code

We imported a new class, transformer.util.Parameters, since we will use predefined constants of this class in method getParameters().

Array args is now created in order to contain 6 String.

Parameters are stored in args like this :

• args[i] : contains the name of the parameter,
• args[i + 1] : contains the value of the parameter,

We used predefined constants to build the name of the parameters. You could have used the litteral string written in comment on the same line to produce an equivalent effect.

The path of our 3 parameters is given as relative. For parameters -xml_in and -xsl, path is relative to where the application will be launched ( editor/test). For parameter -grp_dtd, path is given relative to the XML document to transform (editor/XML/XML/ex1.cd).

As we used relative paths, the location from where the application is launched is very important. If we had used absolute path instead, the application could have been launched from anywhere.

2.2.3. Running the code

Run the example with this command (depending on the OS you run it, you will not use the same classpath separator) :

    java -classpath ../lib/taxi.jar;. XMLToGRPTest (under Windows)
    java -classpath ../lib/taxi.jar:. XMLToGRPTest (under other OS)
  

You get the following output :

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

Document editor/XML/XML/ex1.cd.grp has been generated and 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. Example 2

In this example, based on example 1, we will use an XML parameter document and override some values.

3.1. Code

Modify editor/test/XMLToGRPTest.java (changes are indicated in bold) :

    import fr.loria.taxi.transformer.TransformerXMLToGRP;
    import fr.loria.taxi.transformer.util.Parameters;
    import fr.loria.taxi.transformer.util.XMLToGRPParameters;


    public class XMLToGRPTest {
      /**
       * This method prepares the parameters needed by the process of transformation. If any
       * error happens, we display an error message and leave the application.
       *
       * @return The list of parameters as an XMLToGRPParameters object.
       */
      public static XMLToGRPParameters getParameters() {
        XMLToGRPParameters parameters = null;

        try {
          // The array containing the parameters
          String[] args = new String[4];

          /*
          // XML document to transform
          args[0] = Parameters.PARAMETER_SIGN + Parameters.XML_IN;  // -xml_in
          args[1] = "../XML/XML/ex1.cd";

          // XSLT stylesheet to use
          args[2] = Parameters.PARAMETER_SIGN + Parameters.XSL;     // -xsl
          args[3] = "../XML/XML/CDtoGRP.xsl";

          // GRP DTD
          args[4] = Parameters.PARAMETER_SIGN + Parameters.GRP_DTD; // -grp_dtd
          args[5] = "../grp.dtd";
          */

          // XML parameter document
          args[0] = Parameters.PARAMETER_SIGN + Parameters.XML;            // -xml
          args[1] = "../XML/XML/parametersCD.xml";

          // Output GRP DTD
          args[2] = Parameters.PARAMETER_SIGN + Parameters.GRP_DTD_OUTPUT; // -grp_dtdoutput
          args[3] = "relative";

          parameters = new XMLToGRPParameters(args);
        } catch (Exception e) {
          // We report any error that might happen with the parameters and leave the application
          System.err.println("-- Something wrong with the parameters --");
          System.err.println(e.getMessage());
          System.exit(1);
        }

        return parameters;
      }


      /**
       * Main method.
       */
      public static void main(String[] args) {
        try {
          // Prepares the list of parameters
          XMLToGRPParameters parameters = getParameters();

          // Creates the Transformer and calls the process() method that operates the process
          // of transformation
          new TransformerXMLToGRP(parameters).process();
        } catch (Exception e) {
          // We report any error that might happen during the process of transformation
          System.err.println("-- Something wrong happened during the transformation --");
          System.err.println(e.getMessage());
        }
      }
    }
  

Open a console, go to directory editor/test (if not already done) and compile XMLToGRPTest.java with the following command :

    javac -classpath ../lib/taxi.jar XMLToGRPTest.java
  

3.2. Explaining the code

In method getParameters(), we specified the use of an XML parameter document which is editor/XML/XML/parametersCD.xml

We overrided the value contained in the XML parameter document for parameter grp_dtdoutput : it will be relative.

3.3. Running the code

Save the following code under editor/XML/XML/parametersCD.xml (absolute paths may be different on your machine, please adapt the code) :

    <?xml version="1.0" encoding="ISO-8859-1"?>
    <!DOCTYPE parameters SYSTEM "../parameters.dtd">
    <parameters>
      <xml_in>D:/editor/XML/XML/ex1.cd</xml_in>
      <xsl>D:/editor/XML/XML/CDtoGRP.xsl</xsl>
      <grp_dtd output="absolute">D:/editor/XML/grp.dtd</grp_dtd>
    </parameters>
  

Run the example with this command (depending on the OS you run it, you will not use the same classpath separator) :

    java -classpath ../lib/taxi.jar;. XMLToGRPTest (under Windows)
    java -classpath ../lib/taxi.jar:. XMLToGRPTest (under other OS)
  

You get the following output :

    Applying XSL transformations to file D:/editor/XML/XML/ex1.cd
    Generating GRP file D:/editor/XML/XML/ex1.cd.grp
  

Document editor/XML/XML/ex1.cd.grp has been generated and 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>
  

You can see that the GRP DTD is indicated as relative in the intermediary document while it was asked to be absolute in the XML parameter document.

4. List of parameters

The list of parameters you can use to construct the array args is exactly the same than the one you are allowed to use when transforming from a console :

Here is the list of constants defined by class transformer.util.Parameters that you can use to build the name of the parameters for transforming XML to GRP :