Current version: 0.97 (Dec 13th 2004) - Add XMLNSDefaultNamespace directive.
mod_xmlns adds XML Namespace support to Apache, and may form the basis of XML-driven publishing systems. It runs as an output filter, so it works automatically with any content generator.
From Version 0.9 (May 1st 2004) it has moved from experimental prototype to provisionally stable (i.e. there's nothing that is known to need changing before it can be declared stable). This hasn't entirely held, as the API has had to be updated. Now the API is shared with mod_publisher, and is being documented.
The basic API for Namespace implementations is:
struct xmlns.ap_register_provider
with provider_group=xmlns, provider_name=your_namespace and your choice
of version string (see the XMLNSUseNamespace directive).The API is documented in xmlns.h. A programming guide is in preparation.
mod_xmlns implements namespaces as an output filter, so the first
configuration directive required to use namespaces is to insert it
in the processing chain with AddOutputFilter,
SetOutputFilter, or AddOutputFilterByType.
The filter name is xmlns.
Syntax: XMLNSUseNamespace URI [on|off] [version]
Activates or deactivates processing for namespace URI, using the processor defined in the version paramater.
Syntax: XMLNSDefaultNamespace URI
Sets a URI to use as default namespace (for un-namespaced elements).
Syntax: XMLNSCommentHandlers on|off
Turns on or off comment handlers defined in namespace implementations. Default is On.
Syntax: XMLNSCommentRemove on|off
Determines whether to strip comments that are not processed by any namespace handler. Default is to pass comments through intact.
A very simple example namespace processor is provided for XHTML, acting on any elements in namespace http://www.w3.org/1999/xhtml:
This XHTML handler serves to ensure XHTML is fully compliant with Appendix C, and can be served to current and legacy Web browsers as text/html. This could be used as an output filter for XML-based publishing systems that don't explicitly support Appendix C compatibility.
By registering a comment handler, we can combine the above with implementing Server-Side Includes (SSI) in XHTML.
Firstly, we create a set of callbacks. For XHTML, we will need Start Element and End Element. An additional handler for Comments may be used to implement SSI.
#include "xmlns.h"
#include <http_config.h>
#include <ap_provider.h>
#define XHTML10 "http://www.w3.org/1999/xhtml"
static apr_status_t hstart(
xmlns_public* ctx,
const parsedname* name,
const xml_attr_t* atts) {
Print the element, attributes and (for the root element) xmlns in the default namespace.
IF the element is defined as empty, append an Appendix C space
before " />". If it is not defined as empty,
do not use this abbreviated form even if this instance of the
element is empty.
Also some basic housekeeping - see the source.
return APR_SUCCESS ; /* suppress the default handler doing anything */
}
static apr_status_t hend(
xmlns_public* ctx,
const parsedname* name) {
if ( element is not defined as empty ) {
print end tag for element ;
}
return APR_SUCCESS ;
}
static apr_status_t hcomment(
xmlns_public* ctx,
const xml_char_t* data) {
/* Dispatch SSI processing based on the first word of the comment.
Return status code according to whether anything interesting happened. */
}
Having defined the handlers, we now create an
xmlns struct containing them. This is slightly changed
from the previous implementation.
static xmlns xmlns_xhtml10 = {
hstart , /* StartElement Handler */
hend , /* EndElement Handler */
NULL , /* StartNamespace Handler */
NULL , /* EndNamespace Handler */
"#", /* Comment Prefix */
hcomment /* Comment Handler */
} ;
Finally, we declare the basic Apache module struct. We use the ap_provider API to make our processor available to mod_xmlns for the XHTML 1.0 namespace:
static void xhtml_hooks(apr_pool_t* pool) {
ap_register_provider(pool, "xmlns", XHTML10 , "1.0", &xmlns_xhtml10) ;
}
module AP_MODULE_DECLARE_DATA xhtml10_module = {
STANDARD20_MODULE_STUFF,
NULL,
NULL,
NULL,
NULL,
NULL,
xhtml_hooks
} ;
The data structs referenced above are defined in xmlns.h.
The following three directives will ensure you can send .xhtml files as text/html without breaking in browsers:
Some examples of the kind of applications enabled by mod_xmlns include:
A parser for namespace http://www.edge-delivery.org/esi/1.0 implements the ESI Language Specification 1.0. Implementation is not updated for the current API.
Implementing collaborative authoring and end-user notes as annotations in a document, in the manner of blogged comments but attached to specific sections of a source document.
May happen when I can find some time.
I don't know if this will work, but since JSP 2.0 is defined as an XML namespace, it should in principle be possible. Together with mod_gcj it could offer a full JSP implementation within Apache, dispensing with the overhead of a Java backend.
mod_xmlns is a minimalist SAX parser, and has no support for DTDs and external entities, nor does it offer much scope for sanity checks on markup being processed. A compatible but richer companion module mod_publisher is in development.
The API is undergoing updates (documentation to follow). See current svn for the state of the art. Updates include rationalisation and additional features: principally the ability for namespace providers to register handlers for XML characters and CDATA.
(this is available in svn release 22, and will work with xmlns software developed between 2004 and early 2006).
mod_xmlns.c source code, the xmlns.h header file for namespace implementations and the mod_xhtml XHTML processor are available under the GNU General Public License (GPL).
In the event of this module being accepted by the Apache Software Foundation, it will be re-licensed under the Apache License.
The old mod_xmlns is still available, and includes the ESI 1.0 parser (not yet updated).
Please contact the developer regarding support for other namespaces.