NAME
Element - A module that captures the values of a typical XML element, including references to parents, children, attributes, namespaces, and all enclosing information.
DESCRIPTION
The purpose of this module is to mimic the behavior of the GGF's NM-WG parsing elements found in the java implementation of perfSONAR. Although the java version consists of a single specialized element for each known XML element, this class presents a generic 'element' structure that can be configured in any possible way.
SYNOPSIS
use Element;
# consder that we wish to make this XML:
#
# <nmwg:store xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
# <nmwg:metadata id="m1">
# <netutil:subject xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" id="s1">
# <nmwg:eventType>snmp.1.3.6.1.2.1.2.2.1.10</nmwg:eventType>
# </nmwg:metadata>
# <nmwg:data id="d1" metadataIdRef="m1" />
# </nmwg:store>
my $store = new Element();
$store->setLocalName("store");
$store->setPrefix("nmwg");
$store->setURI("http://ggf.org/ns/nmwg/base/2.0/");
$store->setQName($store->getPrefix().":".$store->getLocalName());
$store->addAttribute("xmlns:nmwg","http://ggf.org/ns/nmwg/base/2.0/");
my $md = new Element();
$md->setLocalName("metadata");
$md->setPrefix("nmwg");
$md->setURI("http://ggf.org/ns/nmwg/base/2.0/");
$md->setQName($md->getPrefix().":".$md->getLocalName());
$md->setID("m1");
$md->addAttribute("id","m1");
my $subject = new Element();
$subject->setLocalName("subject");
$subject->setPrefix("netutil");
$subject->setURI("http://ggf.org/ns/nmwg/characteristic/utilization/2.0/");
$subject->setQName($subject->getPrefix().":".$subject->getLocalName());
$subject->addAttribute("xmlns:netutil","http://ggf.org/ns/nmwg/characteristic/utilization/2.0/");
$subject->setID("s1");
$subject->addAttribute("id","s1");
my $event = new Element();
$event->setLocalName("eventType");
$event->setPrefix("nmwg");
$event->setURI("http://ggf.org/ns/nmwg/base/2.0/");
$event->setQName($event->getPrefix().":".$event->getLocalName());
$event->setValue("snmp.1.3.6.1.2.1.2.2.1.10");
my $d = new Element();
$d->setLocalName("data");
$d->setPrefix("nmwg");
$d->setURI("http://ggf.org/ns/nmwg/base/2.0/");
$d->setQName($d->getPrefix().":".$d->getLocalName());
$d->setID("d1");
$d->addAttribute("id","d1");
$d->addAttribute("metadataIdRef","m1");
$md->addChild($subject);
$md->addChild($event);
$store->addChild($md);
$store->addChild($d);
$store->print();DETAILS
This object is depened upon the XML::SAX parser, as well as our custom handler to populate an object tree from an XML instance. It is possible to build XML instances through a series of API calls as well.
API
There are many get/set methods, as well as the ability to output an element (and childrent) into readable XML.
new($package)
Creates a new object, does not support the passing of any initial values.
setParent($self, $parent)
The parent is the element that directly encloses a particular element. This method allows a reference to be set so the parent can be easily tracked.
getParent($self)
Returns the value of the parent element.
setID($self, $id)
If an element contains an attribute for 'id', it is set here. Otherwise a randomly genereated number will be used.
getID($self)
Returns the id value of an element.
setPrefix($self, $prefix)
Sets the 'prefix', a shortcut that maps a string to the namespace URI for an element.
getPrefix($self)
Returns the prefix of an element.
setURI($self, $uri)
Sets the URI of the namespace for an element.
getURI($self)
Returns the namespace URI of an element.
setLocalName($self, $localname)
Sets the local (non namespace tied) name of an element.
getLocalName($self)
Returns the local (non-prefixed) name of an element.
setQName($self, $qname)
Sets the qualified (prefixed to a namespace) name of an element.
getQName($self)
Returns the qualified (prefixed) name of an element.
setValue($self, $value)
Sets the text value of an element.
getValue($self)
Returns the text value of an element.
addChild($self, $child)
Adds the element 'child' to the child array of an element.
getChildByName($self, $childname)
Returns the 'first' child element that matches the supplied name.
getChildByID($self, $childid)
Returns the child element that matches the supplied id.
getChildByIndex($self, $index)
Returns the child element for a particular 'index' value in the child element array.
addAttribute($self, $name, $value)
Adds an attribute/value pair to an element.
getAttributeByName($self, $name)
Returns the value of an attribute that matches the supplied name.
print($self, $indent)
Prints the XML output for a element and all of it's children. This module is overloaded to support the standard perl print.
indent($indent)
Given a numeric value, prints spaces equal to this value to 'pretty print' the XML output.
SEE ALSO
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.