Saxon/C  0.2
Saxon Processor library for C/C++
 All Classes Functions Variables
Saxon/C Documentation

Back to web page

Saxon/C is an alpha release of Saxon-HE on the C/C++ programming platform. APIs are offered currently to run XSLT 2.0 from C/C++ or PHP applications.

Platforms supported: Linux and Windows

Installation:

Saxon-HEC:

To install the Saxon-HEC alpha release, unzip the the file libsaxon-HEX-setup.zip and execute the command './libsaxon-HEX-setup' First step is to select the destination of where the product files will be installed. The product files are unpacked in the directory 'Saxon-HEC'

You need to setup the environment for the jet jvm. The jvm is in the directory JET-home=Saxonica-HEC/rt The directory JET-home/lib/i386 must be listed in the LD_LIBRARY_PATH environment variable. For instance, if you are using bash or Bourne shell, use the following commands:

export LD_LIBRARY_PATH=/usr/lib/rt/lib/i386:$LD_LIBRARY_PATH

We assume that the 'rt' directory is in the location /usr/lib. The Saxon-HEC API assumes the library is installed as follows: '/usr/lib/libsaxon.so'

PHP extension:

To build the php extension follow the steps below:

Run the commands:

Update the php.ini file (if using ubuntu it is usually in the location '/etc/php5/apache2/') to contain the php extension: insert the following in the Dynamic Extensions section: extension=saxon.so

Check that the extension has installed properly:

Getting started:

To get started please browse the Saxon/C API starting with the class SaxonProcessor class which acts as a factory class for generating the processors.

C/C++

See the C code along with the build and run script are in the folder 'c'.

C++:


    SaxonProcessor *processor = new SaxonProcessor();
    XsltProcessor * xslt = processor->newTransformer();
    cout<<"Hello World"<<endl;
    cout<<"Test output: "<<xslt->xsltApplyStylesheet("cat.xml","test.xsl")<<endl;

    SaxonProcessor * processor = new SaxonProcessor(false);
    processor->setcwd("/var/www/trax");
    XsltProcessor * xslt = processor->newTransformer();
        xslt->setSourceFile("xml/foo.xml");
    XdmValue * xdmvaluex = new XdmValue("string", "Hello to you");
    if(xdmvaluex !=NULL){
        cerr<< "xdmvaluex ok"<<endl;            
    }
    xslt->setParameter("", "a-param", xdmvaluex);
        const char * resultxx = test->xsltApplyStylesheet(NULL, "xsl/foo.xsl");
    if(resultxx != NULL) {
        cerr<<resultxx<<endl;
    } else {
        cerr<<"Result is NULL"<<endl;
    }
    processor->clearParameters();
    processor->clearProperties();

See the files SaxonProcessor.cpp, XsltProcessor.cpp and XQueryProcessor.cpp

To compile the sample C++ program remove the line '#include 'php_saxon.h' in the file xsltProcessor.cc then execute the command:

g++ -m32 -o xsltProcessor xsltProcessor.cc -ldl -L . libsaxon.so -lstdc++

PHP

PHP API

SaxonProcessor class


SaxonProcessor() //constructor
XdmValue createXdmValue($value) //Create an XdmValue object. Value can be a boolean, int or string type
void setSourceValue(XdmValue $value) //The source used for a query or stylesheet. Requires an XdmValue object
void setSourceFile(string $filename) //The source used for query or stylesheet. Requires a file name as string
XdmValue parseString(string $str) // Create an Xdm node value from string 
XdmValue parseFile(string  $filename) // Create an Xdm node value from file
void setParameter(string $name, XdmValue $value) //Set the parameters required for XSLT stylesheet
void setProperty(string $name, string $value) // Set properties for Query or stylesheet.
void clearParameters()
void clearProperties()
void setStylesheetContent(string $str) //Stylesheet supplied as string
void setStylesheetFile(string $filename) // Stylesheet suplied as a file
void setQueryContent(string $str) // query supplied as a string
void setQueryFile($string $filename) // query supplied as a file
void transformToFile(string $outfilename) // compile and execute the stylesheet. Save the result to file
string transformToString() // compile and execute the stylesheet. Result returned as string. If there are failures then a null is returned
XdmValue transformToValue() // compile and execute the stylesheet. Result returned as an XdmValue object. If there are failures then a null is returned
void queryToFile(string $outfilename) // compile and evaluate the query. Save the result to file
XdmValue queryToValue() // compile and evaluate the query. Result returned as an XdmValue object. If there are failures then a null is returned
string queryToString() // compile and evaluate the query. Result returned as string. If there are failures then a null is returned
void exceptionClear()
void close() // close the Resources used by Saxon/C, such as the JVM. This can only be done once in a process.
string getErrorCode(int $i) // Get the ith error code if there are any errors
string getErrorMessage(int $i) // Get the ith error message if there are any error
int getExceptionCount() // Get number of error during execution or evaluate of stylesheet and query, respectively
string version() // Report the java Saxon-HE version 

XdmValue class

The XdmValue class is created via the createXdmValue method in the SaxonProcessor class

In the Saxon/C download please see the PHP file 'xsltExamples.php' in the 'samples' folder which contains many useful examples which will get you started. Example code from the xsltExamples.php file:


    <?php 
            $xmlfile = "xml/foo.xml";
            $xslFile = "xsl/foo.xsl";
        $proc = new SaxonProcessor();
                $version = $proc->version();
                echo 'Saxon Processor version: '.$version;
                $proc->setSourceFile($xmlfile);
                $proc->setStylesheetFile($xslFile);      
                $result = $proc->transformToString();               
        if($result != null) {               
          echo 'exampleSimple1:
'; echo 'Output:'.$result; } else { echo "Result is null"; } $proc->clearParameters(); $proc->clearProperties(); ?>

In the example below we show how to debug if something unexpected is happening. It is also very useful to examine the apache error.log file:


    <?php 
            $xmlfile = "xml/foo.xml";
            $xslFile = "xsl/foo.xsl";
        $proc = new SaxonProcessor();
                $proc->setSourceFile($xmlFile);
                $proc->setStylesheetFile($xslFile);
                $result = $proc->transformToString();
                if($result == NULL) {
                    $errCount = $proc->getExceptionCount();
                    if($errCount > 0 ){ 
                        for($i = 0; $i < $errCount; $i++) {
                           $errCode = $proc->getErrorCode(intval($i));
                           $errMessage = $proc->getErrorMessage(intval($i));
                           echo 'Expected error: Code='.$errCode.' Message='.$errMessage;
                       }
                        $proc->exceptionClear();    
                    }
                }                
                echo $result;
                $proc->clearParameters();
        $proc->clearProperties();
    ?>

Also look at the file xslt30TestSuite.php

Technical Information:

Saxon/C is built by cross compiling the Java code of Saxon-HE 9.5 using the Excelsior Jet tool. This generates platform specific machine code, which we interface with C/C++ using the Java Native Interace (JNI).

The PHP interface is in the form of a C/C++ PHP extension to Saxon/C created using the Zend module API.

The XML parser used is the one supplied by the Excelsior JET runtime. There are currently no links to libxml.

Limitations:

The following limitations apply to the alpha release, but we expect to remove them in later releases:

Feedback/Comments:

Please use the help forums and bug trackers at saxonica.plan.io if you need help or advice.