NAME
Handler - A module that acts as an XML element handler for a SAX parser (Specifically from the XML::SAX family).
DESCRIPTION
The job of a handler is to listen for SAX events, and act on the information that is passed from the parsing system above. The particular handler relies on objects of type 'Element' for storage, and requires the use of an external stack to manage intereactions of these objects.
SYNOPSIS
use XML::SAX::ParserFactory;
use Data::Stack;
use Handler;
use Element;
my $file = "store.xml"
# set up the stack
my $stack = new Data::Stack();
my $sentinal = new Element();
$sentinal->setParent($sentinal);
$stack->push($sentinal);
# parse with a custom handler
my $handler = Handler->new($stack);
my $p = XML::SAX::ParserFactory->parser(Handler => $handler);
$p->parse_uri($file);
#get the object of the 'root' element
my $element = $stack->peek()->getChildByIndex(0);
#print the element
$element->print();DETAILS
This code is dependent upon the output of the underlying SAX system. There are many SAX parsers, many of which have different features. We have found that the XML::SAX library offers more features than others (such as XML::Parser::SAX). Using this handler with a different library may result in unexpected behavior.
API
The API is not meant to be called by the user, and all (with the exception of one) functions represent events that will be generated by the SAX parser.
new($package, $stack)
The '\%conf' hash contains arguments supplied to the service by the user (such as log files). Creates a new handler object, a external stack (of type Data::Stack) MUST be passed in. This stack is the only way to access the finished element tree after parsing has finished.
start_document($self)
This event indicates the document has started parsing, it is not used in this handler.
end_document($self)
This event indicates the document is done parsing, it is not used in this handler.
start_element($self, $element)
When an element is started, we allocate a new element object and populate it with the necessary information:
Local Name - Non-prefixed name of the element
Prefix - Prefix that maps to a namespace URI.
Namespace URI - URI that indicates an element's membership.
Qualified Name - Prefix + Local Name of an element.
Attributes - name/value pairs of information in the element.
Children - Array of child elements that are 'within' this element.
Parent - The element that the 'parent' (directly above) this element.Additionally, we keep track of namespace nesting to ensure that namespaces are only declared once per scope. The element, once populated, is pushed on to the stack, and the previous top of the stack is marked as the 'parent' of this element.
end_element($self, $element)
When the end of an element is seen we must pop the stack (to indicate that this element has ended) and expose the next 'parent' element. We also update the namespace counter.
characters($self, $characters)
If bare characters are discovered in an XML document, the 'characters' event is triggered. Most times this event may indicate whitespace, and a simple regex can be used to exit if this is the case. When the event is meaningful, we wish to pass the seen value back to the element that resides on the top of the stack by populating it's 'Value' field.
genuid()
Generates a random number. This auxilary function is used to generate an ID value for elements who are not assigned one.
SEE ALSO
Element, XML::SAX, Data::Stack
To join the 'perfSONAR-PS' mailing list, please visit:
https://mail.internet2.edu/wws/info/i2-perfsonarThe perfSONAR-PS subversion repository is located at:
https://svn.internet2.edu/svn/perfSONAR-PS Questions and comments can be directed to the author, or the mailing list.
AUTHOR
Jason Zurawski, <zurawski@eecis.udel.edu>
COPYRIGHT AND LICENSE
Copyright (C) 2007 by Jason Zurawski
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.