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.