Yax - First Steps

Installation

The following description refers to Version 0.11.0.

We assume

  • you are working on a Windows system,
  • you have got a Java runtime installed on your System,
  • you install Yax into your your <installation directory> c:/test,
  • you install all aditional components/application into your <component directory> c:/develop.

Unzip the downloaded file into your <installation directory>. After unzipping the file you will find a subdirectory called yax_0.11.0.

So your <home directory> is c:/test/yax_0.11.0.

Run first Example

Example1.1 is the most classic exercise for a pipeline processor: An input of XML Data will be transformed by some cocatinated

XSLT scripts and persisted as an XML File. Fulfill the following steps to proceed this example:

Go to the <home directory>.

Run runExample1.1.bat from the command line:

c:\test\yax_0.11.0>runExample1.1.bat

You get something like:

WARN   [Configuration] use Console Logger due to Log4J is not installed (resp. a
ccessible)(running mode: command line)
INFO   [Configuration] Using XML Catalog resolver class 'org.apache.xml.resolver
.tools.ResolvingXMLFilter'.
IOException: Cannot run program "dot": CreateProcess error=2, Das System kann di
e angegebene Datei nicht finden
IOException: Cannot run program "dot": CreateProcess error=2, Das System kann di
e angegebene Datei nicht finden
INFO   [root:yax.root] Reading input file 'c:\test\yax_0.11.0\examples\example1.
1.xml' into Context '1'.
WARN   [XSLT:trans1] system default transformer will be used due to transformer
class 'com.icl.saxon.TransformerFactoryImpl' is not reachable
INFO   [XSLT:trans1] Transforming with stylesheet 'transformation1.1.xsl' using
'Saxon6'.
WARN   [XSLT:trans2] system default transformer will be used due to transformer
class 'com.icl.saxon.TransformerFactoryImpl' is not reachable
INFO   [XSLT:trans2] Transforming with stylesheet 'transformation2.xsl' using 'S
axon6'.
WARN   [XSLT:trans3] system default transformer will be used due to transformer
class 'com.icl.saxon.TransformerFactoryImpl' is not reachable
INFO   [XSLT:trans3] Transforming with stylesheet 'transformation3.xsl' using 'S
axon6'.
INFO   [root:yax.root] Writing output file 'c:\test\yax_0.11.0\test\example1.1.o
utput.cmd.xml' from Context '1'.
INFO   Yax run sucessful completed.

Within this bulk of messages you will find several warnings. The actual messages you will receive, obviously depends on your installation. Usually the majority of warnings appears due to missing installations of (respective missing reference to) :

  • Log4j logging framework ("... use Console Logger due to Log4J is not installed...")
  • Graphviz Visualizer ("Cannot run program "dot"...")
  • Saxon XML Processor ("system default transformer will be used... due to ... 'com.icl.saxon.TranformerFactoryImpl' is not reachable")

For solving the problems refer to section "Solving the Problems". Although you should already find the following outputs:

  • <home directory>/test/example1.1.output.cmd.xml

    is the data result of running the pipeline.

  • <home directory>/example1.1.config.xml

    is a part of Yax's logging. The file represents yax's implementation and configuration status.

After solving the Graphviz problem you will also get

  • <home directory>/examples/example1.1.pipeTrace.png and <home directory>/examples/example1.1.portTrace.png

    are other parts of Yax's logging. The files depict the pipeline graphically in different granularity (pipeTrace > coarse grained and port Trace > fine grained).

After solving all problems you should get a bulk of messages on the console like:

 INFO [Configuration] Using XML Catalog resolver class 'org.apache.xml.resolver.
tools.ResolvingXMLFilter'.
 INFO [root:yax.root] Reading input file 'c:\test\yax_0.11.0\examples\example1.1
.xml' into Context '1'.
 INFO [XSLT:trans1] Transforming with stylesheet 'transformation1.1.xsl' using '
Saxon6'.
 INFO [XSLT:trans2] Transforming with stylesheet 'transformation2.xsl' using 'Sa
xon6'.
 INFO [XSLT:trans3] Transforming with stylesheet 'transformation3.xsl' using 'Sa
xon6'.
 INFO [root:yax.root] Writing output file 'c:\test\yax_0.11.0\test\example1.1.ou
tput.cmd.xml' from Context '1'.
 INFO Yax run sucessful completed.

As last part of Yax's logging you will find a log file containing the same bulk of messages you have seen on the console at:

  • <home directory>/log/\yax.log.

Run next Example

Go to your <home directory>.

Run runExample8.bat.

You get something like:

 INFO [Configuration] Using XML Catalog resolver class 'org.apache.xml.resolver.
tools.ResolvingXMLFilter'.
Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/fop/apps/F
OPException
        at java.lang.Class.forName0(Native Method)
        at java.lang.Class.forName(Unknown Source)
        at net.sf.yax.types.ComponentTypeFactory.getClassesFromDirectory(Compone
ntTypeFactory.java:213)
        at net.sf.yax.types.ComponentTypeFactory.retrieveImplementedTypes(Compon
entTypeFactory.java:112)
        at net.sf.yax.types.ComponentTypeFactory.<init>(ComponentTypeFactory.jav
a:46)
        at net.sf.yax.Implementation.<init>(Implementation.java:28)
        at net.sf.yax.Implementation.getInstance(Implementation.java:35)
        at net.sf.yax.Queue.setComponentType(Queue.java:78)
        at net.sf.yax.Queue.init(Queue.java:53)
        at net.sf.yax.YaxFactory$PipelineHandlerImpl.configure(YaxFactory.java:1
362)
        at net.sf.yax.Yax.run(Yax.java:42)
        at net.sf.yax.Yax.main(Yax.java:31)

This happens due to missing installation of, respective fault reference to the Fop libraries.

So, if you install Fop (http://xmlgraphics.apache.org/fop/) into your <component directory> you will receive something like:

 INFO [Configuration] Using XML Catalog resolver class 'org.apache.xml.resolver.
tools.ResolvingXMLFilter'.
 INFO [Load:Load xml file] Reading input file 'c:\test\yax_0.11.0\examples\fop\x
ml\projectteam.xml' into Context '2'.
 INFO [XSLT:transform to fo] Transforming with stylesheet 'projectteam2fo.xsl' u
sing 'Saxon6'.
 INFO [FOP:write pdf] Writing output file 'c:\test\yax_0.11.0\test\example8.pdf'
 from Context '2'.
 INFO [root:yax.root] Writing output file 'c:\test\yax_0.11.0\.\yaxOutput.xml' f
rom Context '2'.
 INFO Yax run sucessful completed.

As Fop is realized as a custom step type, refer also to the section 'Solving the Problems'>'Make Custom Types available',

Solving the Problems

Make Log4j available

For Yax the prefered logging framework is Log4j. Although Yax also works without any configured logging system. Out of the box, yax writes all log messages to the console. if Log4j is reachable for Yax, it will be used.

So, for using the Log4j simply install it (http://logging.apache.org/log4j/) to your <component directory>. The bat files already contains a reference to the Log4j resources. If you prefer another location for your components, modify the reference accordingly.

@echo off

set cp=
set cp=%cp%;lib\de.opsdesign.yax.core.jar
set cp=%cp%;lib\xml-resolver-1.2.jar
set cp=%cp%;configuration
set cp=%cp%;.
set cp=%cp%;c:\develop\apache-log4j-1.2.15\log4j-1.2.15.jar
set cp=%cp%;c:\develop\saxon6-5-3\saxon.jar

set script=examples/example1.1.xproc
set input=examples/example1.1.xml
set output=test/example1.1.output.cmd.xml

java -classpath %cp% de.opsdesign.yax.Yax %script% %in% %out%

Yax comes with a log4j customization. You find the log4j.properties at <installation directory>/configuration/log4j.properties.

Make XML Catalog available

XML usually contains links to other local or remote resources. References to DTDs or XML Schemas are good examples:

<?xml version="1.0" encoding="UTF-8"?>
<yax:preferences xmlns:yax="http://www.opsdesign.de/yax/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.opsdesign.de/yax/1.0 http://www.opsdesign.de/yax/dtd/1.0/yaxpreferences.xsd">
...
<yax:preferences>

Tools and applications uses these links to reference the linked resources. Often such reference triggers a remote access to the linked recources.

But sometimes such remote accesses are not possible or not desired. There comes XML Catalog into play. XML Catalog defines (inter alia) an open standard for mapping from URI to other URIs. By this way you can avoid remote accesses without modifying your sources.

The following catalog is the content of XMLSpy's CustomCatalog.xml. It maps the URI prefix of the preference schema to a local directory.

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog Catalog.xsd">
  <rewriteURI uriIdStartString="http://www.opsdesign.de/yax/dtd/1.0/" rewritePrefix="file://c:\test\yax_0.11.0\configuration\"/>
</catalog>

When you edit the preference.xml file now, for validating the file XMLSpy references the local yaxpreferences.xsd at c:\test\yax-0.11.0\config\yaxpreferences.xsd instead of the remote one at http://www.opsdesign.de/yax/dtd/1.0/yaxpreferences.xsd.

Make Graphviz available

Download (via http://www.graphviz.org/) and install Graphviz as a normal application.

Add the Graphviz bin directory to your system path.

When you running our example now, you should not get the "...could not run "dot"..." message any further, but should receive the appropriate output.

Make Saxon 6.5.3 available

For using the Saxon xml transformer download (http://www.saxonica.com/) it and place a reference to the saxon.jar file into your classpath:

@echo off

set cp=
set cp=%cp%;lib\de.opsdesign.yax.core.jar
set cp=%cp%;lib\xml-resolver-1.2.jar
set cp=%cp%;configuration
set cp=%cp%;.
set cp=%cp%;c:\develop\apache-log4j-1.2.15\log4j-1.2.15.jar
set cp=%cp%;c:\develop\saxon6-5-3\saxon.jar
set script=examples/example1.1.xproc
set input=examples/example1.1.xml
set output=test/example1.1.output.cmd.xml

java -classpath %cp% de.opsdesign.yax.Yax %script% %in% %out%

Make underlying components available for ant

For using the Saxon (or some other) xml transformer different to xalan, you simply add the necessary jars of that transformer to your classpath.

But doing this with Ant you have to consider some classloader particularities of ant... or simple act as described in the following.

It is not enough to add the jars to the nested classpath,

<project name="net.sf.yax.ant.runViaAnt" default="all" basedir=".">
  <property name="saxon6-5-3.dir" value="c:/develop/saxon6-5-3"/>
  <path id="saxon6-5-3.classpath">
    <pathelement location="${saxon6-5-3.dir}/saxon.jar"/>
    <pathelement location="${saxon6-5-3.dir}/saxon-jdom.jar"/>
  </path>
  <path id="yax.classpath">
    <pathelement location="."/>
    <pathelement location="lib"/>
    <pathelement location="configuration"/>
    <pathelement location="lib/de.opsdesign.yax.core.jar"/>
    <pathelement location="lib/de.opsdesign.yax.ant.jar"/>
    <pathelement location="lib/xml-resolver-1.2.jar"/>

    <path refid="saxon6-5-3.classpath"/>
  </path>
  <taskdef name="yax" classname="de.opsdesign.yax.tools.YaxTask">
    <classpath refid="yax.classpath"/>
  </taskdef>
  <target name="all" depends="clear,runExample1.2"/>
  <target name="runExample1.2">
    <yax ...
</project>

you also have to lead ant with the -lib option to the location of the transformer binaries:

c:\test\yax_0.11.0>ant -lib c:/develop/saxon6-5-3 -f runExample2.xml

Who are interested in the background of this issue may refer to http://ant.apache.org/faq.html#delegating-classloader

Make Custom Types available

Yax provides an easy way to extend the feature realm. Yax scans the <installation directory> for a subdirectory called 'custom' and loads all custom StepType and ComponentType classes found.

Beside the other subdirectories you find a directory called 'custom'. This directory is dedicated for cutom type classes. All type classes Yax find in this directory, will be considered by initializing the available types.

By adding this directory to your classpath you enable yax using all custom types. The other way around, if it is omitted from the classpath all custom won't be considered.

@echo off

set cp=
set cp=%cp%;lib\de.opsdesign.yax.core.jar
set cp=%cp%;lib\xml-resolver-1.2.jar
set cp=%cp%;custom
set cp=%cp%;configuration
set cp=%cp%;.
set cp=%cp%;c:\develop\apache-log4j-1.2.15\log4j-1.2.15.jar
set cp=%cp%;c:\develop\saxon6-5-3\saxon.jar

set fop.dir=c:\develop\fop-0.94

set cp=%cp%;%fop.dir%\lib\avalon-framework-4.2.0.jar
set cp=%cp%;%fop.dir%\lib\batik-all-1.6.jar
set cp=%cp%;%fop.dir%\lib\commons-io-1.3.1.jar
set cp=%cp%;%fop.dir%\lib\commons-logging-1.0.4.jar
set cp=%cp%;%fop.dir%\lib\serializer-2.7.0.jar
set cp=%cp%;%fop.dir%\lib\xalan-2.7.0.jar
set cp=%cp%;%fop.dir%\lib\xercesImpl-2.7.1.jar
set cp=%cp%;%fop.dir%\lib\xml-apis-1.3.02.jar
set cp=%cp%;%fop.dir%\lib\xmlgraphics-commons-1.2.jar
set cp=%cp%;%fop.dir%\build\fop.jar

set script=examples/example8.xproc

set params=
set params=%params%-Dexamples.data.dir=examples/fop/xml 
set params=%params%-Dexamples.script.dir=examples/fop/xslt 
set params=%params%-Dtest.dir=test 
set params=%params%-DxmlInput=projectteam.xml 
set params=%params%-Dxml2foScript=projectteam2fo.xsl 
set params=%params%-DpdfOutput=example8.pdf

java -classpath %cp% de.opsdesign.yax.Yax %script% %params%