NAME

perfSONAR_PS::Services::MA::Topology - A module that provides methods for a Topology Service. The Topology Service can be used to make Topology Data available to individuals via webservice interface.

DESCRIPTION

This module, in conjunction with other parts of the perfSONAR-PS framework, handles specific messages from interested actors in search of Topology data.

There are two major message types that this service can act upon: QueryRequest/SetupDataRequest - Allows queries to the database TopologyChangeRequest - Allows updates to the topology database =head1 API

init Called at startup by the daemon when this particular module is loaded into the perfSONAR-PS deployment. Checks the configuration file for the necessary items and fills in others when needed. Initializes the backed metadata storage (Oracle Sleepycat XML Database). Finally the message handler registers the appropriate message types and eventTypes for this module. Any other 'pre-startup' tasks should be placed in this function.

registerLS($self $sleep_time) Given the service information (specified in configuration) and the contents of our xmldb backend, we can contact the specified LS and register the top-level identifiers (a summarized form of the elements in the database).

buildLSMetadata ($id, $type, $prefix, $url) This function is used to build the metadata that is registered with the LS. This element contains the prefix and the local name of the element to be register as well as the id for that element.

handleEvent This is the function that is called by the daemon whenever a metadata/data pair with one of our eventTypes is found in a message we've regeistered in.

handleQueryRequest ($self, $output, $eventType, $m, $d) This function handles the (hopefully to be standardized) QueryRequest message. The semantics of the message are as follows:

    If no subject is included, the semantics are "give me the whole database",
    and a XQuery for "//*" (i.e. everything) is submitted to the backend database.

    If an xquery subject is included, the semantics are "use the included
    XQuery to query the database". It simply passes the included XQuery to the
    backend database.

    If any other subject is included, an invalid subject error is thrown.

handleSetupDataRequest ($self, $output, $eventType, $m, $d) This function handles the older protocol's query mechanism. The semantics of the message are as follows:

    If an "http://ggf.org/ns/nmwg/topology/query/all/20070809" eventType is
    included in the metadata, the entire backend database is returned.

    If an "http://ggf.org/ns/nmwg/topology/query/xquery/20070809" eventType is
    included in the metadata, an xquery subject must be included as well. The
    xquery inside the xquery subject will be passed to the backend database.

handleChangeTopologyRequest The hope is to standardize the information changing protocol between the LS and the Topology Service. In the interim, this handler handle metadata/data pairs corresponding to the current TS protocol.

    The metadata contains an eventType specifying how the data should modify
    the backend database and the data contains a topology wrapper containing
    the topology elements to add or update.

    If the eventType is "http://ggf.org/ns/nmwg/topology/change/add/20070809",
    the elements in the data segment are added to the database. If any of the
    elements (based on identifiers), already exist in the database, an error is
    returned. 

    If the eventType is
    "http://ggf.org/ns/nmwg/topology/change/update/20070809", the elements in
    the data segment are merged with the existing elements with the same
    identifier in the database. If any element in the data segment does not
    exist in the database, an error will be returned.

    If the eventType is
    "http://ggf.org/ns/nmwg/topology/change/replace/20070809", the elements in
    the data segment are added to the database. If any of the elements already
    exist in the database, they will be replaced with the element in the data
    segment.

SEE ALSO

perfSONAR_PS::Services::Base, perfSONAR_PS::Services::MA::General, perfSONAR_PS::Common, perfSONAR_PS::Messages, perfSONAR_PS::Client::LS::Remote, perfSONAR_PS::Topology::Common, perfSONAR_PS::Client::Topology::XMLDB

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

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.