NAME
perfSONAR_PS::Services::MA::General - A module that provides methods for general tasks that MAs need to perform, such as querying for results.
DESCRIPTION
This module is a catch all for common methods (for now) of MAs 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).
SYNOPSIS
use perfSONAR_PS::Services::MA::General;
use perfSONAR_PS::Common;
# Consider this metadata:
#
# <nmwg:metadata xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" id="1">
# <netutil:subject xmlns:netutil="http://ggf.org/ns/nmwg/characteristic/utilization/2.0/" id="stout">
# <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:direction>in</nmwgt:direction>
# </nmwgt:interface>
# </netutil:subject>
# <select:parameters xmlns:nmwg="http://ggf.org/ns/nmwg/base/2.0/" id="2">
# <nmwg:parameter xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/" name="time" operator="gte">
# 1176480310
# </nmwg:parameter>
# <nmwg:parameter xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/" name="time" operator="lte">
# 1176480340
# </nmwg:parameter>
# <nmwg:parameter xmlns:select="http://ggf.org/ns/nmwg/ops/select/2.0/" name="consolidationFunction">
# AVERAGE
# </nmwg:parameter>
# </select:parameters>
# </nmwg:metadata>
# note that $node is a LibXML node object.
my $queryString = "/nmwg:metadata[".
getMetadataXQuery($node, "").
"]/\@id";
# the query after should look like this:
#
# /nmwg:metadata[
# netutil:subject/nmwgt:interface/nmwgt:ifAddress[
# @type="ipv4" and text()="128.4.133.167"
# ] and
# netutil:subject/nmwgt:interface/nmwgt:hostName[text()="stout"] and
# netutil:subject/nmwgt:interface/nmwgt:ifName[text()="eth1"] and
# netutil:subject/nmwgt:interface/nmwgt:direction[text()="in"]
# ]/@id
# The same use case works for data elements, using 'getDataXQuery'
# the time structure should look like this:
#
# {
# 'START' => '1173723350',
# 'END' => '1173723366'
# 'CF' => 'AVERAGE'
# 'RESOLUTION' => ''
# };
getTime($ma, $id);
my @dbSchema = ("id", "time", "value", "eventtype", "misc");
my $result = getDataSQL($ma, $d, \@dbSchema);
if($#{$result} == -1) {
# error
}
else {
for(my $a = 0; $a <= $#{$result}; $a++) {
# unroll results
}
}
my $responseString = adjustRRDTime($ma);
if(!$responseString) {
my %rrd_result = getDataRRD($ma, $d, $mid);
if($rrd_result{ERROR}) {
# error
}
else {
foreach $a (sort(keys(%rrd_result))) {
foreach $b (sort(keys(%{$rrd_result{$a}}))) {
# unroll results
}
}
}
}
else {
# error
}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 offered API is basic for now, until more common features to MAs can be identified and utilized in this module.
getMetadataXQuery($node, $queryString)
Given a metadata node, constructs and returns an XQuery statement.
getSPXQuery($node, $queryString)
Helper function for the subject and parameters portion of a metadata element. Used by 'getMetadataXQuery', not to be called externally.
getEventTypeXQuery($node, $queryString)
Helper function for the eventType portion of a metadata element. Used by 'getMetadataXQuery', not to be called externally.
getDataXQuery($node, $queryString)
Given a data node, constructs and returns an XQuery statement.
xQueryParameters($node, $path, $queryCount, $queryString)
Helper function for the parameters portion of NMWG elements, not to be called externally.
xQueryAttributes($node, $path, $queryCount, $queryString)
Helper function for the attributes portion of NMWG elements, not to be called externally.
xQueryText($node, $path, $queryCount, $queryString)
Helper function for the text portion of NMWG elements, not to be called externally.
xQueryEventType($node, $path, $queryString)
Helper function for the eventTYpe portion of NMWG elements, not to be called externally.
getTime($request, $ma, $id, $default_resolution)
Performs the task of extracting time/cf/resolution information from the request message.
findTime($parameter, $timePrefix, $type)
Extracts the time values from the parameter elements, and converts formats if necessary.
getDataSQL($ma, $d, $dbSchema)
Returns either an error or the actual results of an SQL database query.
getDataRRD($ma, $d, $mid)
Returns either an error or the actual results of an RRD database query.
adjustRRDTime($ma)
Given an MA object, this will 'adjust' the time values in an data request that will end up quering an RRD database. The time values are only 'adjusted' if the resolution value makes them 'uneven' (i.e. if you are requesting data between 1 and 70 with a resolution of 60, RRD will default to a higher resolution becaues the boundaries are not exact). We adjust the start/end times to better fit the requested resolution.
SEE ALSO
Exporter, Log::Log4perl, perfSONAR_PS::Common, perfSONAR_PS::Messages
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. Bugs, feature requests, and improvements can be directed here:
https://bugs.internet2.edu/jira/browse/PSPSVERSION
$Id: General.pm 692 2007-11-02 12:36:04Z zurawski $
AUTHOR
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.