NAME
perfSONAR_PS::Common - A module that provides common methods for performing simple, necessary actions within the perfSONAR-PS framework.
DESCRIPTION
This module is a catch all for common methods (for now) in the perfSONAR-PS framework. As such there is no 'common thread' that each method shares. This module IS NOT an object, and the methods can be invoked directly (and sparingly).
DETAILS
The API for this module aims to be simple; note that this is not an object and each method does not have the 'self knowledge' of variables that may travel between functions.
API
The API of perfSONAR_PS::Common offers simple calls to common activities in the perfSONAR-PS framework.
find($node, $query, $return_first) This function replicates the libxml "find" function. However, it formats the query to work around some oddities in the find implementation. It converts the xpath query to get rid of direct references like /nmwg:element and replaces them with /*[name()='nmwg:element"] which avoids spurious 'undefined namespace' errors. It also wraps the find in an eval and returns 'undef' if ->find throws an errors. If the $return_first is set to one, the function returns only the first node from the nodes found.
findvalue($node, $query) This function is analogous to the libxml "findvalue" function. However, it makes use of the 'find' function documented above. Unlike the libxml findvalue function, this function will only return the text contents of the first node found.
makeEnvelope($content) Wraps the specified content in a soap envelope and returns it as a string.
readXML($file) Reads the file specified in '$file' and returns the XML contents in string form. The <xml> tag will be extracted from the final returned string. Function will warn on error, and return an empty string.
chainMetadata($dom) Given a dom of objects, this function will continuously loop through performing a 'chaining' operation to share values between metadata objects. An example would be:
<nmwg:metadata id="1" xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/">
<netutil:subject xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" id="1">
<nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/">
<nmwgt:ifAddress type="ipv4">128.4.133.167</nmwgt:ifAddress>
<nmwgt:hostName>stout</nmwgt:hostName>
</nmwgt:interface>
</netutil:subject>
<nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
</nmwg:metadata>
<nmwg:metadata id="2" xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" metadataIdRef="1">
<netutil:subject xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" id="2">
<nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/">
<nmwgt:ifName>eth1</nmwgt:ifName>
<nmwgt:ifIndex>3</nmwgt:ifIndex>
<nmwgt:direction>in</nmwgt:direction>
</nmwgt:interface>
</netutil:subject>
<nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0</nmwg:eventType>
</nmwg:metadata>
Which would then become:
<nmwg:metadata id="2">
<netutil:subject xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" id="1">
<nmwgt:interface xmlns:nmwgt="http://ggf.org/ns/nmwg/topology/2.0/">
<nmwgt:ifAddress type="ipv4">128.4.133.167</nmwgt:ifAddress>
<nmwgt:hostName>stout</nmwgt:hostName>
<nmwgt:ifName>eth1</nmwgt:ifName>
<nmwgt:ifIndex>3</nmwgt:ifIndex>
<nmwgt:direction>in</nmwgt:direction>
</nmwgt:interface>
</netutil:subject>
<nmwg:eventType>http://ggf.org/ns/nmwg/tools/snmp/2.0/</nmwg:eventType>
</nmwg:metadata>
This chaining is useful for 'factoring out' large chunks of XML.defaultMergeMetadata ($parent, $child) This function will try to merge the specified parent metadata into the child metadata. It will do this by first merging their subjects, then copying all the eventTypes from the parent into the child and then merging all the parameters blocks from the parent into the child.
defaultMergeParameters($parent, $child) This function simply does a simple merge of the parent and child subject element. If an element exists in the parent and not the child, it will be added. If an element exists in both, an attempt will be made to merge them. The only special case elements are parameter elements where the 'name' attribute is checked to verify the equivalence. In all other case, the elements name and namespace will be compared and if they're the same, the function assumes that the child's should supercede the parent's.
defaultMergeParameters($parent, $child) This function takes parent and child parameter blocks and adds each parameter element from the parent into the child. If a parameter by the same name and namespace already exists in the child, the function will merge the two parameters. In the case of a parameter with only a 'value' attribute and no body, the child's will simply replace the parent. In the case that elements exist as children below the parameter, the parameters will be merged.
mergeNodes_general($old_node, $new_node, $attrs)
Takes two LibXML nodes containing structures and merges them together.
The $attrs variable is a pointer to a hash describing which attributes
on an element node should be compared to define equality. If an element's
name is not defined in the hash, the element is simply replaced if one of
the same name and namespace is found.
To have links compared based on their 'id' attribute, you would specify $attrs as such:
my %attrs = (
link => ( id => '' );
);countRefs($id, $dom, $uri, $element, $attr) Given a ID, and a series of 'struct' objects and a key 'value' to search on, this function will return a 'count' of the number of times the id was seen as a reference to the objects. This is useful for eliminating 'dead' blocks that may not contain a trigger. The function will return -1 on error.
genuid() Generates a random number.
extract($node) Returns a 'value' from a xml element, either the value attribute or the text field.
mapNamespaces($node, \%namespaces) Fills in a uri -> prefix mapping of the namespaces.
reMap(\%{$rns}, \%{$ns}, $dom_node) Re-map the nodes namespace prefixes to known prefixes (to not screw with the XPath statements that will occur later).
consultArchive($host, $port, $endpoint, $request) This function can be used to easily consult a measurement archive. It's a thin wrapper around the sendReceive function in the perfSONAR_PS::Transport module. You specify the host, port and endpoint for the MA you wish to consult and the request you wish to send. The function sends the request to the MA, parses the response and returns to you the LibXML element corresponding to the nmwg:message portion of the response. The return value an array of the form ($status, $res) where status is 0 means the function was able to send the request and get a properly formed response and -1 on failure. $res contains the LibXML element on success and an error message on failure.
escapeString($string) This function does some basic XML character escaping. Replacing < with <, & with &, etc.
unescapeString($string) This function does some basic XML character escaping. Replacing < with <, & with &, etc.
mergeConfig($base, $specific) Merges the configurations in $base and $specific.
convertISO($iso) Given the time in ISO format, conver to 'unix' epoch seconds.
SEE ALSO
Exporter, IO::File, XML::XPath, Time::HiRes, Log::Log4perl
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-PSQuestions and comments can be directed to the author, or the mailing list.
VERSION
$Id$
AUTHOR
Aaron Brown <aaron@internet2.edu>, Jason Zurawski, zurawski@internet2.edu
LICENSE
You should have received a copy of the Internet2 Intellectual Property Framework along with this software. If not, see <http://www.internet2.edu/membership/ip.html>
COPYRIGHT
Copyright (c) 2004-2007, Internet2 and the University of Delaware
All rights reserved.