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.

resolveMetadataChain($metadata, $dom) Given a metadata and a dom, this function will resolve the metadata chain and merge the specified metadata with all its parent elements.

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.

getPath($node) Cleans up the 'path' (XPath location) of a node by removing positional notation, and the root elements. This path is then returned. Note this function should not be called externally.

elements($node, $original, $extra) Given a node (and knowing what the original structure looks like) adds 'missing' elements when needed. Note this function should not be called externally.

attributes($node, $original) Given a node (and knowing what the original structure looks like) adds 'missing' attributes. Note this function should not be called externally.

exact($node, $original) Checks parameter nodes for 'exact' matches. Note this function should not be called externally.

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 &lt;, & with &amp;, etc.

unescapeString($string) This function does some basic XML character escaping. Replacing &lt; with <, &amp; 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-perfsonar

The 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.

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.