XProc-Z

XProc-Z is an application framework designed for XML-literate programmers to build web applications of various kinds (web sites, web services, web APIs, web proxies, etc) in the XML-based scripting languages XProc, XSLT, and XQuery.

XProc-Z itself is written in Java, but building a web application with it requires no knowledge of Java or Java compilation.

XProc-Z uses the XProc interpreter Calabash, by Norm Walsh, to execute pipelines. The XProc-Z framework itself does little except connect Calabash to the HTTP protocol.

XProc; a language for data plumbing

XProc is a language for writing XML pipelines; it uses the idea of data “flowing” from various sources, step by step through a network of pipes and filters, to reach its destination. It’s a language for data plumbing.

XProc is a language purpose built for XML processing tasks. For instance it takes only a dozen or so lines of code to read a bunch of XML files from a website, transform them with an XSLT, validate them with a schema, and finally save the valid files in one folder and the invalid files in another.

Running XProc programs on the Web

XProc is not intended primarily for writing web servers, and most XProc programs are not web applications. Most XProc pipelines are run from the command line where they can read from the Web, and write to the Web using the `http-request` feature of the XProc language, but they aren’t themselves actually part of the Web. However, there are some application frameworks which allow you to run your XProc pipelines in the context of a web server, and configure your pipelines to receive HTTP requests and make HTTP responses. One example is the "Pipe Rack" framework offered by Calabash itself.

XProc-Z is different from other XProc web frameworks in the details of the mechanisms by which an HTTP request is passed to your pipeline, and in which your pipeline outputs its response. For instance, if a browser makes an HTTP “POST” request for a resource with a particular URI, and passes it a bunch of parameters encoded in the “application/x-www-form-urlencoded” format, somehow that request has to invoke a particular pipeline, and pass those parameters to it. Generally, XProc-Z web frameworks have their own framework for this; some of them were quite restrictive; a URI directly identifies a pipeline, and any URI parameters were passed to the pipeline as pipeline parameters; others were more flexible; allow you to tweak it so that various properties of a request, taken together, identified which pipeline to run; you could pass not just form parameters, but other things, such as HTTP request headers, to the pipeline, and so on. Generally, to customize the way the HTTP request was handled you have to write some Java code, or write some custom XML configuration file. XProc-Z is less "opinionated" about how a pipeline responds to a request; it leaves the details up to the pipeline itself. This provides the following advantages:

• You can write an application entirely in the XProc language, without any Java coding or compilation. In the library world, and in the Digital Humanities community, there are a lot of people who know XML, and know XSLT, and for whom XProc could be a really easy next step. XProc-Z is designed to support those users.
• You can write XProc applications that handle any kind of HTTP request. You can handle not only GET and POST, but also PUT, HEAD, and so on. Your application can have access not only to URI request parameters, but also to cookies, HTTP request headers, multipart content uploads, and so on.

XProc-Z's HTTP binding mechanism

For maximum flexibility, an XProc-Z application consists of a single XProc pipeline. When XProc-Z receives an HTTP request it passes the request to that pipeline, and leaves it up to the pipeline itself to decide how to handle any headers, parameters, and so on. An XProc pipeline that didn’t need to know about the HTTP Accept header, for instance, could just ignore that header, but the header would always be passed to it anyway, just in case.

To pass the request to the pipeline, and to retrieve the response, XProc-Z reuses a mechanism already present in the XProc language, which just had to be turned inside out. XProc has a step called http-request, and associated request and response XML document types. In XProc, an HTTP request is made by creating a request document containing the details of the request, and piping the document into an http-request step, which actually makes the HTTP request, and in turn outputs a response document. By following this pattern, XProc-Z makes use of the existing definitions of request and response, and does not have to add any extraneous or “foreign” mechanisms. In XProc-Z’s binding mechanism, an HTTP request received from a web user agent is converted into a request object and passed into the XProc-Z pipeline. The output of the pipeline is expected to be a response document, which XProc-Z converts into an actual HTTP response to the web user agent. In other words, an XProc-Z pipeline has the same signature as the standard XProc http-request step, which makes a lot of sense if you think about it.

This means that an XProc-Z server can make do with a single pipeline which handles any request. The pipeline can parse the request in an arbitrary way; using cookies, parsing URI parameters and HTTP headers, accepting PUT and POST requests, and returning arbitrary HTTP response codes and headers. The business of “routing” request URIs and parsing parameters is all left up to the XProc pipeline itself. So the binding mechanism is very simple and leaves maximum flexibility to the pipeline, which can then be used to implement any kind of HTTP based protocol.