NAME

XSLT::Cache - Transparent preparsing and caching XSLT documents

SYNOPSIS

 # Running under mod_perl
 my $tr = new XSLT::Cache(timeout => 60);
 . . .
 sub handler {
     . . .
     $html = $tr->transform('/www/server/index.xml');
     . . .
 }
    

ABSTRACT

XSLT::Cache provides a mechanism for transparent caching XSLT files and checking their updates.

DESCRIPTION

Using XSLT in real life often leads to the need of preliminary parsing and caching XSLT documents before applying them to incoming XML trees. This module makes caching transparent and allows the user not to think about that. It is possible to make cache available for some time interval. If a file was once stored to the cache, it will be available even after it is deleted from disk.

new

Builds a new instance of cache object.

 my $tr = new XSLT::Cache;
 

This method accepts two optional named parameters that define behaviour of cache.

 my $tr = new XSLT::Cache(
     prefix  => '/www/data/xsl',
     timeout => 600     
 );

prefix parameter determines where XSLT files are located. By default they are looked for in the current directory.

timeout defines duration (in seconds) of the period of unconditional using cache. Before timeout happens transformation are always executed with an XSLT-document from cache, even if original file was modified or deleted.

transform

To apply a transformation it is only needed to call transform method.

 say $tr->transform($xml_document);
 

First argument should contain XML document that is to be transformed. It may be either a reference to XML::LibXML::Document object, or a path to XML file on disk, or text variable containing XML as a text.

Return value is a scalar containing transformation result as text.

Here is an example of how to use XML document which is already built. Note that the document itself may also be cached with the help of File::Cache::Persistent module.

 my $xmlparser = new XML::LibXML;
 my $xmldoc = $xmlparser->parse_file('/www/xml/index.xml');
 my $html = $tr->transform($xmldoc);

Passing filename allows to avoid manual reading and parsing of XML.

 $html = $tr->transform('/www/xml/index.xml');

And, finally, it is possible to pass XML text directly.

 $html = $tr->transform(<<XML);
 <?xml version="1.0" encoding="UTF-8"?>
 <?xml-stylesheet type="text/xsl" href="/www/data/transform.xsl"?>
 <my_document>
     . . .
 </my_document>
XML

Path to XSLT file must either be specified in the XML document itself or be passed as a second argument of transform method.

Passing the path to XSLT file in the ducument requires xml-stylesheet processing instruction:

 <?xml-stylesheet type="text/xsl" href="data/transform.xsl"?>

XSLT location is always affected by prefix argument if it was used in object constructor.

How cache works

Caching logic is simple. Every XSLT file took place in a transformation is beeing put to the cache. When another query to make the same transformation is received, and there were no timeout specified, the file is checked and if it is modified, it is re-read and cache is updating; otherwise current cached document is used.

If caching object was built with a timeout specified, it never makes any checks before timeout happen.

When a transformation is found in the cache but original file is already deleted from disk, cached copy will always be used, even before timeout period.

status

This method allows to learn out which version was used for the transformation and returns the status of last transform call. Return valus are described in details in appropriate section of File::Cache::Persistent module documentation.

SEE ALSO

XML::ApplyXSLT module offeres similar functionality.

Detailed logic of checking file modifications is described in a documentation of File::Cache::Persistent module.

AUTHOR

Andrew Shitov, <andy@shitov.ru>

COPYRIGHT AND LICENSE

XSLT::Cache module is a free software. You may redistribute and (or) modify it under the same terms as Perl itself whichever version it is.

cpanm XSLT::Cache

perl -MCPAN -e shell
install XSLT::Cache