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.