NAME

perfSONAR_PS::Client::LS::Remote - A module that provides a client API for an LS

DESCRIPTION

This module aims to offer simple methods for dealing with requests for information, and the related tasks of interacting with backend storage.

SYNOPSIS

    use perfSONAR_PS::Client::LS::Remote;

    my %conf = ();
    $conf{"SERVICE_ACCESSPOINT"} = "http://someorganization.org:8080/perfSONAR_PS/services/service";
    $conf{"SERVICE_NAME"} = "Some Organization's Service MA"
    $conf{"SERVICE_TYPE"} = "MA"
    $conf{"SERVICE_DESCRIPTION"} = "Service MA"

    my $ls = "http://someorganization.org:8080/perfSONAR_PS/services/LS";

    my $ls_client = perfSONAR_PS::Client::LS::Remote->new($ls, \%conf, \%ns);

    # or
    # $ls_client = perfSONAR_PS::Client::LS::Remote->new;
    # $ls_client->setURI($ls);
    # $ls_client->setConf(\%conf);
    # $ls_client->setNamespaces(\%ns);

    $ls_client->registerStatic(\@data);

    $ls_client->sendKeepalive($conf{"SERVICE_ACCESSPOINT"});

    $ls_client->sendDeregister($conf{"SERVICE_ACCESSPOINT"});

    my $ls2 = "http://otherorganization.org:8080/perfSONAR_PS/services/LS";

    my $ls_client2 = perfSONAR_PS::Client::LS::Remote->new($ls2);

    my %queries = ();

    $queries{"req1"} = "";
    $queries{"req1"} .= "declare namespace nmwg=\"http://ggf.org/ns/nmwg/base/2.0/\";\n";
    $queries{"req1"} .= "for \$data in /nmwg:store/nmwg:data\n";
    $queries{"req1"} .= "  let \$metadata_id := \$data/\@metadataIdRef\n";
    $queries{"req1"} .= "  where \$data//*:link[\@id=\"link1\"] and \$data//nmwg:eventType[text()=\"http://ggf.org/ns/nmwg/characteristic/link/status/20070809\"]\n";
    $queries{"req1"} .= " return /nmwg:store/nmwg:metadata[\@id=\$metadata_id]\n";

    $queries{"req2"} = "";
    $queries{"req2"} .= "declare namespace nmwg=\"http://ggf.org/ns/nmwg/base/2.0/\";\n";
    $queries{"req2"} .= "for \$data in /nmwg:store/nmwg:data\n";
    $queries{"req2"} .= "  let \$metadata_id := \$data/\@metadataIdRef\n";
    $queries{"req2"} .= "  where \$data//*:link[\@id=\"link2\"] and \$data//nmwg:eventType[text()=\"http://ggf.org/ns/nmwg/characteristic/link/status/20070809\"]\n";
    $queries{"req2"} .= " return /nmwg:store/nmwg:metadata[\@id=\$metadata_id]\n";

    my ($status, $res) = $ls_client2->query(\%queries);
    if ($status != 0 or not defined $res{"req1"} or not defined $res{"req2"}) {
      print "Error: querying $ls2 failed\n";
      exit(-1);
    }

    my ($query_status, $query_res);

    ($query_status, $query_res) = $res{"req1"};

    if ($query_status != 0) {
      print "Couldn't get information on query req1: ".$query_res."\n";
      exit(-1);
    } else {
      print "Results for res1: ".$query_res->toString()."\n";
    }

    ($query_status, $query_res) = $res{"req2"};

    if ($query_status != 0) {
      print "Couldn't get information on query req2: ".$query_res."\n";
      exit(-1);
    } else {
      print "Results for res1: ".$query_res->toString()."\n";
    }

API

The offered API is simple, but offers the key functions we need in a measurement archive.

new ($package, $uri, \%conf)

The parameters are the URI of the Lookup Service, a %conf describing the service for registration purposes.

The %conf can have 4 keys in it:

SERVICE_NAME - The name of the service registering data SERVICE_ACCESSPOINT - The URL for the service registering data SERVICE_TYPE - The type (MA, LS, etc) of the service registering data SERVICE_DESCRIPTION - A description of the service registering data

setURI ($self, $uri) (Re-)Sets the value for the LS URI.

setConf ($self, \%conf) (Re-)Sets the value for the 'conf' hash.

createKey ($self, $key) Creates a 'key' value that is used to access the LS.

createService ($self) Creates the 'service' subject (description of the service) for LS registration.

callLS ($self, $sender, $message) Given a message and a sender, contact an LS and parse the results.

sendDeregister ($self, $key) Deregisters the data with the specified key

sendKeepalive ($self, $key) Sends a keepalive message for the data with the specified key

registerStatic ($self, \@data_ref) Performs registration of 'static' data with an LS. Static in this sense indicates that the data in the underlying storage DOES NOT change. This function uses special messages that intend to simply keep the data alive, not worrying at all if something comes in that is new or goes away that is old.

__register ($self, $subject, $data_ref) Performs the actual data registration. Unlike the above registration functions, this function does not try to perform any of the keepalive/deregister registration tricks. It simply registers the specified data. As part of the registration, it splits the data into chunks and registers each independently.

registerDynamic ($self, \@data_ref) Performs registration of 'dynamic' data with an LS. Dynamic in this sense indicates that the data in the underlying storage DOES change. This function uses special messages that will remove all old data and insert everything brand new with each registration.

query ($self, \%queries) This function sends the specified queries to the LS and returns the results. The queries are given as a hash table with each key/value pair being an identifier/a query. Each query gets executed and the returned value is a hash containing the same identifiers as keys, but instead of pointing to queries, they point to an array containing a status and a result. The status is either 0 or -1. If it's 0, the result is a pointer to the data element. If it's -1, the result is the error message.

SEE ALSO

Log::Log4perl, perfSONAR_PS::Common, perfSONAR_PS::Transport, perfSONAR_PS::Messages, perfSONAR_PS::Client::Echo

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. Bugs, feature requests, and improvements can be directed here:

  https://bugs.internet2.edu/jira/browse/PSPS

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-2008, Internet2 and the University of Delaware

All rights reserved.