Axamol SAX Pipeline

What is it?

It's a presentation layer for web pages, designed to be used with Jakarta struts, prominently featuring the AXP file format.

AXP is easiest to understand by analogy to Sun's JSP. A JSP file is a text document with Java fragments thrown in. The server compiles it to a Java class that sends output to a PrintWriter in response to HttpServletRequests. AXP does the same thing, except that the files must be well-formed XML, and they send SAX events to a ContentHandler. Usually, the ContentHandler is an XSLT processor, but it could also be a simple serializer.

AXP is also very similar to Apache Cocoon's XSP format.

It's easiest to see what AXP is actually like by looking at a real example. This one is from my messageboard code. It produces an HTML form for posting a message. It remembers previous filled-in values (if you've hit the "Preview" button or had some sort of error) and displays errors resulting from problems in your input. It displays a preview of what your post should look like. It doesn't have much of the HTML boilerplate stuff, since the XSLT it is sent through handles all that.

Here's another example that does a database query. Notice that there's no SQL there and no formatting—the SQL is kept in a Axamol SQL Library and the formatting is done by a generic XSLT stylesheet plus small templates to tweak a couple columns.

(Axamol SAX Pipeline used to be called framework, and AXP used to be called XFP. If you are looking for those, you're in the right place.)

Why would I use it over JSP?

It has several key advantages:

It never forgets to escape user-given input.
With JSPs, a random System.out.println(someVar) is not escaped. Developers have to explicitly pass everything through an escape function themselves. It's a very common problem to lose track of what has and hasn't been escaped. At the least, this is an annoyance to users who enter metacharacters by accident. At the most, it can cause cross-site scripting security vulnerabilities by allowing malicious users to embed Javascript in your pages.

With AXP, a <axp:expr>someVar</axp:expr> is translated into a ContentHandler.characters() SAX call, which escapes automatically. If you want to send an XML fragment as SAX events, you use <sax:parse>someVar</sax:parse> instead. You usually want variables to be escaped, so AXP does so unless you tell it otherwise.
It helps you produce more correct XML. Since each AXP is an XML document, it must be well-formed or it will not compile. It will even help you ensure the SAX you produce dynamically is well-formed. XML produced from within Java code is actually represented by XML tags in the source file. If they're not balanced, it won't compile. If you want to do something more tricky (and dangerous), you still can talk to the ContentHandler yourself.
It's faster when you do further processing. A JSP's output is a stream of characters. So if you are running it through XSLT, you're serializing your XML and parsing it again. That's a waste. A AXP's output is a SAX stream, which can be more directly sent to an XSLT engine.

Why would I want to use it over Cocoon's XSP?

It's simple! I was very pleased when I first found Apache Cocoon; it seemed to do everything that I was planning to do. But I looked through the sitemap necessary for even a "Hello, world"-style page and got depressed. Cocoon tries to do too much. It's intended to handle every page within the web application, rather than letting the servlet container's web.xml sort it out. So you have to learn another configuration file format to dispatch your pages. And it slows down the server to go through the additional layers. It even has a complete logging system that the performance page recommends not using. There's a lot of cruft.

XSP logicsheets are painful. They are XSLT stylesheets that process your code. They destroy information about the current position in the file during compilation, making it hard to find errors. They tie you to a specific programming language, since they actually insert their code in yours. They lead to redundant code. And their horribly complicated XSLT+Java fragments are quite confusing.

AXP tag libraries, in contrast, are modelled after JSP's. They're easy to write and use.

Why would I prefer JSP or XSP over this?

AXP is incomplete and probably buggy. Plus, it doesn't (and never will) have the same sort of recognition as those two. Everyone knows JSP. A small group knows Cocoon. Almost no one knows AXP, though I'd argue that it's easy to pick up very quickly.

How do I use it?

The only user-level documentation at present is this overview of the AXP format. I also recommend looking at how Axamol Message Board is structured.