Apache::AxKit::Language::SAXMachines

NAME
SYNOPSIS
DESCRIPTION

Style Processor Mapping (AxAddStyleMap)
Invoking The Processor (AxAddProcessor, etc.)
Setting Up a Simple SAX Filter Chain (AxSAXMachineFilters)
Using a SAX::Machines-aware Controller Class (AxSAXMachineClass)
When Worlds Collide ( Using Both AxSAXMAchineFilters and AxSAXMachineClass )

SEE ALSO

NAME

Apache::AxKit::Language::SAXMachines - Transform Content With SAX Filters

SYNOPSIS


    # add the style processor mapping
    AxAddStyleMap application/x-saxmachines Apache::AxKit::Language::SAXMachines

    # add the processor
    AxAddProcessor application/x-saxmachines .

    # create a simple filter chain
    PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"

    # filter set-up via a controller class
    PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"

DESCRIPTION

Language::SAXMachines provides an easy way ( via Barrie Slaymaker's XML::SAX::Machines ) to use SAX filter chains to transform XML content.

It is not technically a ``language'' in the same sense that XSP, XPathScript, or XSLT are since there is no stylesheet to write or process. Instead, the SAX filters are added via config directives in your .htaccess or *.conf file.

( Note, future versions may add an associated XML application grammar that may be used to define/configure the filter chain, but rushing forward to that is Truly Bad Idea(tm) for a number of reasons ).

The configuration directives that are required or recognized by Language::SAXMachines are detailed below.

Style Processor Mapping (AxAddStyleMap)

To use Language::SAXMachines you must set set up the mapping between the style processor's MIME type and the Language::SAXMachines module. This is achieved via the typical AxAddStyleMap directive:

    AxAddStyleMap application/x-saxmachines Apache::AxKit::Language::SAXMachines

Invoking The Processor (AxAddProcessor, etc.)

To apply Language::SAXMachines processor to a given document request, you must use the AxAddProcessor directive (or one of its relations):

    <Files *.xml>
      AxAddProcessor application/x-saxmachines .
    </Files>

Note the dot ('.') there. Like XSP, there is no external stylesheet to process so the URI must be set to point back to the document itself.

See the section labeled ``ASSOCIATING STYLESHEETS WITH XML FILES'' in the main AxKit POD ( perldoc AxKit ) for additional options.

Setting Up a Simple SAX Filter Chain (AxSAXMachineFilters)

For simple cases where you want to process the document through a static list of SAX filters, use the AxSAXMachineFilters option. It accepts a white-space-seperated list of valid SAX Filter module names and builds a linear processing pipeline from those modules. Filters are applied in the same order that they appear in the AxSAXMachineFilters directive.

The following would create a simple pipleline that applies the SAX filters XML::Filter1 and XML::Filter2 (in that order) to the document.

    PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"

Using a SAX::Machines-aware Controller Class (AxSAXMachineClass)

A static list of SAX Filters is fine for many tasks. However, for more advanced applications, it is often desireable for sets of filters (or other SAX::Machines) to be dynamically chosen and set up at request time.

The AxSAXMachinesClass directive accpets the module name of a class that is capable of building a SAX::Machines processing chain. The object returned from that module's get_machine() method is expected to a blessed and valid reference to to a SAX::Machine object (including Pipelines, ByRecords, etc.).

The following would use the SAX::Machines object returned by the get_machine() method of the the Custom::MachineBuilderClass module to create the SAX processing chain.

    PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"

In addition, the get_machines() method in the class defined by the AxSAXMachineClass directive is passed a reference to the current Apache::Request instance (as well as few other possibly useful bits of information) allowing the module to create a processing chain that is more directly responsive to the context of the current request. A typical get_machine() implementation might start off like:

   sub get_machine {
       my ($self, $r, $last_in_chain) = @_;

       # make some choices about what filters to add, or machines to build
       # based on the info the Apache::Request object in $r
     
       # assumes 'use XML::SAX::Machines qw( Pipeline );'
       my $machine = Pipeline( @list_of_filters_we_picked ); 
       return $machine;
  }

Note that machines can be nested sets of other machines just as in the regular usage of XML::SAX::Machines, get_machine() need only return the top-level 'wrapper machine'.

When Worlds Collide ( Using Both AxSAXMAchineFilters and AxSAXMachineClass )

In cases where both AxSAXMachineFilters and AxSAXMAchineClass are used to set up the processing for a given request, the machine returned by AxSAXMAchineClass is given processing precedence. That is, the document's event stream will be run through the machine returned by the AxSAXMAchineClass first, and then passed through the filters defined by the AxSAXMAchineFilters directive. So,

    PerlSetVar AxSAXMachineFilters "XML::Filter1 XML::Filter2"
    PerlSetVar AxSAXMachineClass "Custom::MachineBuilderClass"

appearing in the same config block would send the document's events through a linear pipeline consisting of the machine returned by Custom::MachineBuilderClass's get_machine() method followed by the filters XML::Filter1 and XML::Filter2.