Introducing AxKit
by Barrie Slaymaker
|
Pages: 1, 2, 3
How the example works
Later articles in this series will examine various features of AxKit in more depth, for now let's take a look at how the example from the installation section works.
In fact, hopefully by the next article, a new release of AxKit should have a simple demo facility for each of it's major XML processing alternatives available. If so, the tarball accompanying the next article will contain the new release.
The Configuration
AxKit integrates quite tightly with the Apache configuration engine. The Apache configuration engine is far more than a text file parser: it forms the core of Apache's request handling capabilities and is the key to Apache's flexibility and extensibility. The directives added to the server's configuration above are a mix of native Apache directives and AxKit directives. Let's walk through the first part of the request cycle and see how the Apache configuration directives affect the request.
The Apache httpd is primarily a configuration engine and a collection of special-purpose modules. This discussion glosses over the fact that several modules other than mod_perl and AxKit are used to process this request and refers to them all as "Apache".
When the HTTP request arrives, Apache parses it and maps the path portion of the URL ("/") to a location on the harddrive (/home/me/axkit_articles-1.0/www/htdocs). The URI maps to a directory and the Apache directives "DocumentRoot" (not shown, it's part of the default install), "<Directory>", "Options +Indexes" and "DirectoryIndex" cause Apache to map this URI to the file index.xsp.
Now that the underlying resource has been identified, Apache uses the .xsp extension to figure out what module should deliver the resource to the browser. The AddHandler AxKit .xsp directive tells Apache to delegate the response handling to AxKit. This is very similar to establishing a mod_perl handler for a URI except that it is implemented in C and is a bit faster than a standard mod_perl response handler.
The Processing Chain
The test document, index.xsp is an example of XSP, eXtensible Server Pages, one of the several languages that AxKit supports. We'll get to how the XSP is processed in a moment.
When AxKit begins the task of handling the response it has already, through cooperation with Apache's configuration engine processed it's configuration directives. These have the following effects:
- AxDebugLevel 10
- Causes quite a lot of output in the www/logs/error_log,
- AxGzipOutput On
- Enables automatic gzip compression (via Compress::Zlib). This is only used if the client can accept compressed documents. AxKit even goes the extra mile and compresses output for a few clients that can handle it but don't set the HTTP Accept-Encoding: header properly.
- AxAddStyleMap application/x-xsp Apache::AxKit::Language::XSP
- Establishes a mapping between the MIME type "application/x-xsp" and the Apache::AxKit::Language::XSP module. We'll see shortly how this mapping tells AxKit what module to use when applying a type of transform.
- AxAddXSPTaglib
- Notes that the XSP engine needs to load the AxKit::XSP::Util (this supplies some of the Perl code called by index.xsp),
The first thing AxKit needs to do when handling a response is to configure the processing pipeline. The first place AxKit looks for directions is in the source document; it scans the source document for <?xml-stylesheet...?> processing instructions like:
<?xml-stylesheet href="NULL" type="application/x-xsp"?>
AxKit has two alternative mechanisms that provide far more power and flexibility; we'll look at these as we walk through more advanced configurations in later articles.
The xml-stylesheet PIs specify a list of transforms to apply to the source document; these are applied in the order that they occur in the document. Each processing instruction specifies a stylesheet ("NULL" in this case: XSP doesn't use them, we'll cover that in a moment), and a processor type ("application/x-xsp"). The AxAddStyleMap directives specify which Perl modules handle with processor types, and the one in our example maps application/x-xsp to Apache::AxKit::Language::XSP.
That's all quite complex; here's a diagram that shows how the most important bits of this example affect the processing pipeline:
and the resulting pipeline looks like:
As the diagram shows, the source .xsp page is read from disk, then compiled in to Perl source code (using the util: taglib as necessary) and cached on disk. The resulting source code is then run to generate the result document for this request, which is compressed (if the client supports compression), and sent to the client.
You can see the source code in www/logs/error_log when the AxDebugLevel is set to at least 10.
Note that AxKit is smart enough to not cache the output document (there's no cache between the XSP processor and the output); XSP is intended for dynamic pages and its output documents should not be cached.
When index.xsp is compiled, the resulting code builds the output document node by node. The <util:time .../> tag is converted in to a subroutine call that calls perl's localtime function. See the error_log to see the generated Perl (our AxDebugLevel is set to 10, so XSP.pm emits this to the error log), and see the function get_date() in AxKit::XSP::Util for the localtime() call.
XSP and Taglibs
XSP is unlike most XML processing "languages" in that it does not actually use stylesheets; instead, XSP pages contain special tags that are executed each time the page is requested. In index.xsp, for instance, the <util:time format="%H:%M:%S"/> tag is converted in to Perl code which calls localtime.
Most XML filters apply a transform to the source XML to generate the result XML. These transforms are called "stylesheets". As mentioned, XSP does not use stylesheets. We will cover stylesheet based transforms in future articles.
The util: portion of the tag is a prefix indicating that the util taglib will handle that tag. The util: prefix is an XML namespace prefix and is not hard-coded; the xmlns:util attribute in the root element of index.xsp:
<xsp:page
xmlns:xsp="http://www.apache.org/1999/XSP/Core"
xmlns:util="http://apache.org/xsp/util/v1"
>
binds the util: prefix to the taglib. The module that provides the code behind the util: taglib, AxKit::XSP::Util, has the same URI ("http://apache.org/xsp/util/v1") hardcoded in it. When the AxAddXSPTaglib directive is seen in the httpd.conf file, AxKit::XSP::Util registers with the XSP module to handle all tags in that namespace.
An XSP page may include as many taglib namespaces and tags as it needs. CPAN contains a large and growing collection of taglibs for use with AxKit's XSP implementation, and we'll look at two ways of writing taglibs for Apache in the next two articles.
The taglibs approach is superficially similar to many of the templating engines on CPAN; indeed, some of the the templating systems have been extended recently to includ taglibs. There are several important differences between these and XSP, however.
- XSP input files must be well formed XML, this makes it impossible to generate malformed XML. With templating systems, typos in the content markup can easily reach the browser with no warnings.
- The source document may be transformed before it is handed to the XSP processor. This allows you to build simple taglibs as XSLT transforms deployed upstream of the XSP processor. Because AxKit's XSP translates XSP pages in to code and caches the code, these transforms will not be run each request; they are captured in the cached code. This can also be used to "capture" static transforms.
- XSP encourages content, logic, and presentation to be separated; XSP pages add logic to content and generate well formed XML that can be (and usually is) massaged by "real" stylesheets to effect different presentations.
- as with some of the more sophisticated templating systems, XSP is designed to be extensible; adding a taglib is as simple as configuring adding an AxAddXSPTaglib statement to the httpd.conf file and then referring to it in the source document. In the test code, the <util:time> tag is provided by the Apache::XSP::Util module, and you may load as many taglibs as necessary in to the server.
Milepost 1 and the Road Ahead
This is the first article in this series, presenting AxKit's installation and introducing one of AxKit's processing technologies: XSP. In the next article we'll see how to chain together filters to apply stylesheets to both static documents and XSP-generated documents to allow the same documents to be delivered in different forms. Following that we'll examine how to write taglibs in Perl (the recommended approach) using some helper modules, and XSLT.
References and Helpful Resources
There are several very helpful places to research problems, ask questions, and learn more. Try to find others who have had similar problems before posting a question, of course, but the user groups listed here are the place to ask:
- the AxKit web site (which may have moved to an xml.apache.org site by the time you read this)
- The "official" AxKit web site.
- The AxKit Guide
- An in-depth introduction to AxKit.
- The axkit-users@axkit.org mailing list.
- Browse the archives or subscribe. This is the place to discuss AxKit-specific problems and offer solutions, patches and success stories. The mod_perl resources listed here are perfect for general mod_perl build and support issues as well.
- mod_perl Developer's Guide
- The first place to check for Apache+mod_perl build advice and debugging tips.
- modperl@perl.apache.org email archives
- Look here to see if anyone else has had your problems and (usually) found a solution. This list is about to move to an @perl.org address at the time of this writing so I won't point you to a soon-to-be-stale subscription form.
- perl-xml@listserv1.ActiveState.com
- A mailing list for general perl and XML questions, including axkit support. (subscribe at http://listserv.activestate.com/mailman/listinfo/perl-xml).
- The #axkit IRC channel at irc.rhizomatic.net
- A friendly place where you can often get quick advice right from experienced AxKit users and contributors.
As with all online Open Source communities, please do try to pay forward any help you receive.
Thanks to Martin Oldfield, Kip Hampton and Robin Berjon for their thorough technical reviews, though I'm sure I managed to sneak some bugs by them. AxKit and many of the Perl modules it uses are primarily written by Matt Sergeant with extensive contributions from these good folks and others, so many thanks to all contributors as well.
Copyright 2002, Robert Barrie Slaymaker, Jr. All Rights Reserved.
