How AxKit Works
May 24, 2000
|Table of Contents|
AxKit registers two "handlers" with Apache in order to do its work. In Apache terms,
are modules that work in various parts of the request phase (which covers things like
Authentication, Type checking, Response, and Logging). When a request for a file comes
AxKit does some quick checking to see if the file is XML. The main checks performed
see if the file extension is
.xml, and/or to check the first few characters of
the file for the
<?xml?> declaration. If the file is not XML, AxKit lets
Apache deliver the file as it would normally. Note that it's possible to only apply
certain parts of your web site.
When an XML file is detected, the next step is to call plugin modules to determine
media type and/or style sheet preference. Media type chooser plugins normally look
User-Agent header, or possibly at the
Accept header. However,
it's possible to define any method at all to determine the media type.
The existing style sheet choosers are based on examining the path info (this is a
following the filename, so you could request
myfile.xml/mystyle), query string
myfile.xml?style=mystyle), and file suffix
The final part is plumbing together all the style sheets with the XML file in the right order, implementing cascading where appropriate, and also "doing the right thing" with regards to the cache. AxKit invalidates the page cache when external entities (parsed or unparsed) change, as well as when the original document is altered. This allows modular style sheets to change only part of their make-up and ensure that changes to these sub-components cause a re-build of the cache.
AxKit uses two separate methods for mapping XML files to style sheets. The primary
is that specified in the W3C Recommendation at http://www.w3.org/TR/xml-stylesheet. This specifies that an
<?xml-stylesheet?> processing instruction at the beginning of the XML file
<?xml?> declaration, and before the first element) defines the
location and type of the style sheet.
The second method of mapping XML files to style sheets is used when no usable
<?xml-stylesheet?> directives are found in the XML file. This uses a
DefaultStyleMap option in your Apache configuration files. These directives
can be used anywhere within Apache's
<Directory> sections, and
.htaccess configuration system.
In this way it's possible to define complex mapping rules for different file types
locations in whichever manner pleases you, without having each XML file individually
its style sheet.
AxKit then uses the type of the style sheet (in the
pseudo-attribute of the
<?xml-stylesheet?> processing instruction, or the
first parameter of the
DefaultStyleMap option) to decide which module to use to
process the file. Types are mapped to a module using another Apache configuration
AddStyleMap. Again, this directive can appear anywhere within Apache's
configuration structure. This allows you to try different modules for processing the
Often, AxKit will have more than one style sheet option for serving a particular file. How does it choose which one to use?
The choice is made based on media type and on "style sheet preference." For a style sheet to be chosen for the file currently being served, the media types must match, or the style sheet must have a type of "all."
Style sheet preferences are slightly more complex. AxKit has three concepts of style sheets: persistent, preferred, or alternate. Without drowning in detail here, this facility allows a processor further up the "pipeline" to determine a style sheet -- so, for instance, a user could personalize their look and feel by determining which style sheet was applied.
It's easy to get confused by the term "style sheet" here--in AxKit they are not restricted to XSLT sheets, and are best thought of as general processing and transformation stages. Style sheets in AxKit's terms can do anything, provided you can build a Language module to parse it. This includes the function of creating original XML content, as well as transforming and formatting it. So it becomes possible to, for instance, retrieve database results, add tags, and format the result into WML or HTML.
Cascading refers to the case of one style sheet's results "cascading" into the next (alternatively, you can think of this as a pipeline of processing stages). With AxKit there are a number of ways to achieve this. The first and simplest method is to have all your style sheets based on DOM, and produce DOM trees. When all the style sheets have finished processing, AxKit takes care to dispose of your DOM tree and output the result to the user agent.
The second method of cascading is to simply pass around the textual result of your output. This is necessary with modules like Sablotron where there is no DOM tree available. Modules further down the processing stream can parse this result as XML, and continue processing.
The final, and possibly most interesting, method of cascading processing stages is to use "end-to-end SAX." Here, AxKit sets up a chain of SAX handlers to process the document. Each style sheet stage based on SAX simply sends on SAX events to the next SAX handler up the chain. The final SAX handler in the chain simply outputs its results as text to the browser. The key advantage of this end-to-end system is that it starts outputting data to the browser as soon as parsing begins.
This system allows database modules to avoid building DOM trees in memory, which can be very resource intensive, but to simply fire SAX events, and the output from the database will appear as results are available.
Now that we've been through the theory of how AxKit works, it's time to install and start using it. I don't believe in tools like this being hard to use or set up, so provided you can use an editor and modify a few Apache configuration files, installation should be simple.
Obviously, AxKit requires an installed Apache web server. AxKit also requires mod_perl, so if you don't have it already installed, you need to add it into your Apache. Depending on your platform, this can be complex. More information is available at http://perl.apache.org/guide/.
To install AxKit, first download the distribution. Extract the archive and change to the directory it creates. Then type:
perl Makefile.PL make make test make install
(If you don't have 'apxs' in your path, mod_perl versions below 1.24 will produce a warning at the first step. This warning can be ignored.)
Once AxKit is installed, you will need to edit your Apache web server's configuration
files. First you need to enable AxKit so that Apache understands AxKit's configuration
directives, so add the following line to your
Finally, you can add in the core components of AxKit--the XMLFinder and the StyleFinder.
These can be added to any
.htaccess file, or other Apache configuration
PerlTypeHandler Apache::AxKit::XMLFinder PerlHandler Apache::AxKit::StyleFinder AxAddStyleMap text/xsl Apache::AxKit::Language::XSLT
The last line associates the type
text/xsl with its style sheet code
Now you're ready to start serving up XML files. To get started, try looking at the example files in the AxKit distribution.
AxKit provides web developers with the tools they need to deliver complex XML-based systems quickly, and eases them into the development process. It provides the power to develop their own system for style sheet negotiation, and also the flexibility to design completely new style sheet languages.
Although AxKit is not finished yet, the majority of the features described above are built and working reliably. The most significant things missing from AxKit are SAX-based style sheet languages (which need to be designed and built--I have a number of ideas for these) and alternate ways to generate the initial XML file (as opposed to filesystem XML). These will be coming in future releases.
As AxKit is an open source project, I hope people will jump in and help. We have the beginnings of an active mailing list, where you can vote on features, help develop them, or simply lurk. We're moving extremely quickly with the features. Developing in Perl allows us to do this, while still maintaining readable code (something I deem very important -- so don't assume because it's written in Perl that it's going to be a ball of spaghetti!). If there's something you'd like to see in AxKit, please join the mailing list and participate in the project.