NAME
    POE::Filter::XML - A POE Filter for parsing XML

SYSNOPSIS
     use POE::Filter::XML;
     my $filter = POE::Filter::XML->new();

     my $wheel = POE::Wheel:ReadWrite->new(
            Filter          => $filter,
            InputEvent      => 'input_event',
     );

DESCRIPTION
    POE::Filter::XML provides POE with a completely encapsulated XML parsing
    strategy for POE::Wheels that will be dealing with XML streams.

    The parser is XML::LibXML

    Default, the Filter will spit out POE::Filter::XML::Nodes because that
    is what the default XML::SAX compliant Handler produces from the stream
    it is given. You are of course encouraged to override the default
    Handler for your own purposes if you feel POE::Filter::XML::Node to be
    inadequate.

    Also, Filter requires POE::Filter::XML::Nodes for put(). If you are
    wanting to send raw XML, it is recommened that you subclass the Filter
    and override put()

PUBLIC METHODS
    Since POE::Filter::XML follows the POE::Filter API look to POE::Filter
    for documentation. Deviations from Filter API will be covered here.

    new()
        new() accepts a total of four(4) named arguments that are all
        optional: (1) 'BUFFER': a string that is XML waiting to be parsed
        (i.e. xml received from the wheel before the Filter was
        instantiated), (2) 'CALLBACK': a coderef to be executed upon a
        parsing error, (3) 'HANDLER': a XML::SAX compliant Handler, or (4)
        'NOTSTREAMING': boolean telling the filter to not process incoming
        XML as a stream but as single documents.

        If no options are specified, then a default coderef containing a
        simple Carp::confess is generated, a new instance of
        POE::Filter::XML::Handler is used, and activated in streaming mode.

    reset()
        reset() is an internal method that gets called when either a
        stream_start(1) POE::Filter::XML::Node gets placed into the filter
        via put(), or when a stream_end(1) POE::Filter::XML::Node is pulled
        out of the queue of finished Nodes via get_one(). This facilitates
        automagical behavior when using the Filter within the XMPP protocol
        that requires many new stream initiations. This method is also
        called after every document when not in streaming mode. Useful for
        handling XMLRPC processing.

        This method really should never be called outside of the Filter, but
        it is documented here in case the Filter is used outside of the POE
        context.

        Internally reset() gets another parser, calls reset() on the stored
        handler and then deletes any data in the buffer.

    callback()
        callback() is an internal accessor to the coderef used when a
        parsing error occurs. If you want to place stateful nformation into
        a closure that gets executed when a parsering error happens, this is
        the method to use.

BUGS AND NOTES
    The underlying parser was switched to XML::LibXML.

    Also note that the PXF::Nodes returned are now subclassed from
    LibXML::Element and that the underlying API for Nodes has changed
    completely with out ANY compatibility at all. This was done for
    performance reasons, and also to gain XPath capabilities on the nodes
    returned.

    Meta filtering was removed. No one was using it and the increased level
    of indirection was a posible source of performance issues.

    put() now requires POE::Filter::XML::Nodes. Raw XML text can no longer
    be put() into the stream without subclassing the Filter and overriding
    put().

    reset() semantics were properly worked out to now be automagical and
    consistent. Thanks Eric Waters (ewaters@uarc.com).

    A new argument was added to the constructor to allow for multiple single
    document processing instead of one coherent stream. This allows for
    inbound XMLRPC requests to be properly parsed automagically without
    manually touching the reset() method on the Filter.

    Arguments passed to new() must be in name/value pairs (ie. 'BUFFER' =>
    "stuff")

AUTHOR
    Copyright (c) 2003 - 2009 Nicholas Perez. Released and distributed under
    the GPL.