AxKit - an XML Application Server for Apache

DESCRIPTION

AxKit provides the user with an application development environment for mod_perl, using XML, Stylesheets and a few other tricks. See http://axkit.org/ for details.

SYNOPSIS

In httpd.conf:

# we add custom configuration directives
# so this *must* be in httpd.conf *outside* of
# all run time configuration blocks (e.g. <Location>)
PerlModule AxKit

Then in any Apache configuration section (Files, Location, Directory, .htaccess):

# Install AxKit main parts
SetHandler perl-script
PerlHandler AxKit

# Setup style type mappings
AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
AxAddStyleMap application/x-xpathscript \
        Apache::AxKit::Language::XPathScript

# Optionally set a hard coded cache directory
# make sure this is writable by nobody
AxCacheDir /opt/axkit/cachedir

# turn on debugging (1 - 10)
AxDebugLevel 5

Now simply create xml files with stylesheet declarations:

<?xml version="1.0"?>
<?xml-stylesheet href="test.xsl" type="text/xsl"?>
<test>
    This is my test XML file.
</test>

And for the above, create a stylesheet in the same directory as the file called "test.xsl" that compiles the XML into something usable by the browser. If you wish to use other languages than XSLT, you can, provided a module exists for that language. AxKit does not internally have a built-in XSLT interpreter, instead it relies on interfaces to other Perl modules. We currently have interfaces in the core package to XML::Sablotron, XML::LibXSLT, and XML::XSLT.

CONFIGURATION DIRECTIVES

AxKit installs a number of new first class configuration directives for you to use in Apache's httpd.conf or .htaccess files. These provide very fine grained control over how AxKit performs transformations and sends its output to the user.

Each directive below is listed along with how to use that directive.

AxCacheDir

This option takes a single argument, and sets the directory that the cache module stores its files in. These files are an MD5 hash of the file name and some other information. Make sure the directory you specify is writable by either the nobody user or the nobody group (or whatever user your Apache servers run as). It is probably best to not make these directories world writable!

AxCacheDir /tmp/axkit_cache

AxNoCache

Turn off caching. This is a FLAG option - On or Off. Default is "Off". When this flag is set, AxKit will send out Pragma: no-cache headers.

AxNoCache On

AxDebugLevel

If present this makes AxKit send output to Apache's error log. The valid range is 0-10, with 10 producing more output. We recommend not to use this option on a live server.

AxDebugLevel 5

AxStackTrace

This FLAG option says whether to maintain a stack trace with every exception. This is slightly inefficient, as it has to call caller() several times for every exception thrown, but it can give better debugging information.

AxStackTrace On

AxLogDeclines

This option is a FLAG, it is either On, or Off (default is Off). When AxKit declines to process a URI, it gives a reason. Normally this reason is not sent to the log, however if AxLogDeclines is set, the reason is logged. This is useful in figuring out why a particular file is not being processed by AxKit.

If this option is set, the reason is logged regardless of the AxDebugLevel, however if AxDebugLevel is 4 or higher, the file and line number of where the DECLINE occured is logged, but not necessarily the reason.

AxLogDeclines On

AxGzipOutput

This allows you to use the Compress::Zlib module to gzip output to browsers that support gzip compressed pages. It uses the Accept-Encoding HTTP header and some information about User agents who can support this option but don't correctly send the Accept-Encoding header. This option allows either On or Off values (default being Off). This is very much worth using on sites with mostly static pages because it reduces outgoing bandwidth significantly.

AxGzipOutput On

AxTranslateOutput

This option enables output character set translation. The default method is to detect the appropriate character set from the user agent's Accept-Charset HTTP header, but you can also hard-code an output character set using AxOutputCharset (see below).

AxTranslateOutput On

AxOutputCharset

Fix the output character set, rather than using either UTF-8 or the user's preference from the Accept-Charset HTTP header. If this option is present, all output will occur in the chosen character set. The conversion uses the iconv library, which is part of GNU glibc and/or most modern Unixes. It is recommended to not use this option if you can avoid it. This option is only enable if you also enable AxTranslateOutput.

AxOutputCharset iso-8859-1

AxErrorStylesheet

If an error occurs during processing that throws an exception, the exception handler will try and find an ErrorStylesheet to use to process XML of the following format:

<error>
    <file>/usr/htdocs/xml/foo.xml</file>
    <msg>Something bad happened</msg>
    <stack_trace>
        <bt level="0">
            <file>/usr/lib/perl/site/AxKit.pm</file>
            <line>342</line>
        </bt>
    </stack_trace>
</error>

There may potentially be multiple bt tags. If an exception occurs when the error stylesheet is transforming the above XML, then a SERVER ERROR will occur and an error written in the Apache error log.

AxErrorStylesheet text/xsl /stylesheets/error.xsl

AxAddXSPTaglib

XSP supports two types of tag libraries. The simplest type to understand is merely an XSLT or XPathScript (or other transformation language) stylesheet that transforms custom tags into the "raw" XSP tag form. However there is another kind, that is faster, and these taglibs transform the custom tags into pure code which then gets compiled. These taglibs must be loaded into the server using the AxAddXSPTaglib configuration directive.

# load the SQL taglib
AxAddXSPTaglib Apache::AxKit::Language::XSP::SQL
AxAddXSPTaglib Apache::AxKit::Language::XSP::Util

If you prefix the module name with a + sign, it will be pre-loaded on server startup (assuming that the config directive is in a httpd.conf, rather than a .htaccess file).

AxStyle

A default stylesheet title to use. This is useful when a single XML resource maps to multiple choice stylesheets. One possible way to use this is to symlink the same file in different directories with .htaccess files specifying different AxStyle directives.

AxStyle "My custom style"

AxMedia

Very similar to the previous directive, this sets the media type. It is most useful in a .htaccess file where you might have an entire directory for the media "handheld".

AxMedia tv

AxAddStyleMap

This is one of the more important directives. It is responsible for mapping module stylesheet MIME types to stylesheet processor modules (the reason we do this is to make it easy to switch out different modules for the same functionality, for example different XSLT processors).

AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
AxAddStyleMap application/x-xpathscript \
    Apache::AxKit::Language::XPathScript
AxAddStyleMap application/x-xsp \
    Apache::AxKit::Language::XSP

If you prefix the module name with a + sign, it will be pre-loaded on server startup (assuming that the config directive is in a httpd.conf, rather than a .htaccess file).

AxResetStyleMap

Since the style map will continue deep into your directory tree, it may occasionally be useful to reset the style map, for example if you want a directory processed by a different XSLT engine.

# option takes no arguments.
AxResetStyleMap

ASSOCIATING STYLESHEETS WITH XML FILES

There are several directives specifically designed to allow you to build a flexible sitemap that specifies how XML files get processed on your system. These directives are used only if your XML file does not have the <?xml-stylesheet?> directives.

AxAddProcessor

This directive maps all XML files to a particular stylesheet to be processed with. You can do this in a <Files> directive if you need to do it by file extension, or on a file-by-file basis:

<Files *.dkb>
AxAddProcessor text/xsl /stylesheets/docbook.xsl
</Files>

Multiple directives for the same set of files make for a chained set of stylesheet processing instructions, where the output of one processing stage goes into the input of the next. This is especially useful for XSP processing, where the output of the XSP processor will likely not be HTML (or WAP or whatever your chosen output format is):

<Files *.xsp>
# use "." to indicate that XSP gets processed by itself.
AxAddProcessor application/x-xsp .
AxAddProcessor text/xsl /stylesheets/to_html.xsl
</Files>

AxAddDocTypeProcessor

This allows you to map all XML files conforming to a particular XML public identifier in the document's DOCTYPE declaration, to the specified stylesheet(s):

AxAddDocTypeProcessor text/xsl /stylesheets/docbook.xsl \
        "-//OASIS//DTD DocBook XML V4.1.2//EN"

AxAddDTDProcessor

This allows you to map all XML files that specify the given DTD file or URI in the SYSTEM identifier to be mapped to the specified stylesheet(s):

AxAddDTDProcessor text/xsl /stylesheets/docbook.xsl \
        /dtds/docbook.dtd

AxAddRootProcessor

This allows you to map all XML files that have the given root element to be mapped to the specified stylesheet(s):

AxAddRootProcessor text/xsl /stylesheets/book.xsl book

Namespaces are fully supported via the following syntax:

AxAddRootProcessor text/xsl /stylesheets/homepage.xsl \
    {http://myserver.com/NS/homepage}homepage

This syntax was taken from James Clark's Introduction to Namespaces article.

AxAddURIProcessor

This allows you to use a Perl regular expression to match against the URI of the file in question:

AxAddURIProcessor text/xsl /stylesheets/book.xsl \
        "book.*\.xml$"

AxResetProcessors

This allows you to reset the processor mappings at from the current directory level down.

AxResetProcessors

From this directory down you can completely redefine how certain types of files get processed by AxKit.

"><AxMediaType>

This is a configuration directive block. It allows you to have finer grained control over the mappings, by specifying that the mappings (which have to be specified using the Add*Processor directives above) contained within the block are only relevant when the requested media type is as specified in the block parameters:

<AxMediaType screen>
AxAddProcessor text/xsl /stylesheets/webpage_screen.xsl
</AxMediaType>

<AxMediaType handheld>
AxAddProcessor text/xsl /stylesheets/webpage_wap.xsl
</AxMediaType>

<AxMediaType tv>
AxAddProcessor text/xsl /stylesheets/webpage_tv.xsl
</AxMediaType>

"><AxStyleName>

This configuration directive block is very similar to the above, only it specifies alternate stylesheets by name, which can be then requested via a StyleChooser:

<AxMediaType screen>
    <AxStyleName #default>
        AxAddProcessor text/xsl /styles/webpage_screen.xsl
    </AxStyleName>
    <AxStyleName printable>
        AxAddProcessor text/xsl /styles/webpage_printable.xsl
    </AxStyleName>
</AxMediaType>

This and the above directive block can be nested, and can also be contained within <Files> directives to give you even more control over how your XML is transformed.

CUSTOMISING AXKIT

There are some configuration directives that are specifically reserved for customising how AxKit works. These directives allow you to specify a new class to replace the one being used for certain operations.

These directives all take as a single argument, the name of a module to load in place of the default. They are:

AxConfigReader
AxProvider
AxCacheModule

The ConfigReader module returns information about various configuration options. Currently it takes most of its information from the above mentioned configuration directives, or from PerlSetVar.

The Provider module is the means by which AxKit gets its resources from. The default Provider simply picks up files from the filesystem, but alternate providers could pull the information from a DBMS, or perhaps create some XML structure for directories. There currently exists one alternate Provider module, which allows AxKit to work as a recipient for Apache::Filter output. This module is Apache::AxKit::Provider::Filter.

The Cache module is responsible for storing cache data for later retrieval.

Implementing these is non trivial, and it is highly recommended to join the AxKit-devel mailing list before venturing to do so, and to also consult the source for the current default modules. Details of joining the mailing list are at http://axkit.org/mailinglist.xml

KNOWN BUGS

There are currently some incompatibilities between the versions of expat loaded by Apache when compiled with RULE_EXPAT=yes (which is a default, unfortunately), and XML::Parser's copy of expat. This can cause sporadic segmentation faults in Apache's httpd processes. The solution is to recompile Apache with RULE_EXPAT=no (later Apache's have implemented this as --disable-rule=expat). If you have a recent mod_perl and use mod_perl's Makefile.PL DO_HTTPD=1 to compile Apache for you, this option will be enabled automatically for you.

AUTHOR and LICENSE

AxKit is developed by AxKit.com Ltd. See http://axkit.com/ for more details. AxKit.com offer full consultancy services and support for the AxKit product line, and also offer some custom solutions based on AxKit for doing content management, and rendering various other file formats using XML techniques. Contact info@axkit.com for more details.

AxKit is licensed under either the GNU GPL Version 2, or the Perl Artistic License.