NAME

perfSONAR_PS::Services::LS::LS - A module that provides methods for the perfSONAR-PS Single Domain Lookup Service (LS).

DESCRIPTION

This module, in conjunction with other parts of the perfSONAR-PS framework, handles specific messages from interested actors in search of data and services that are registered with the LS. There are four major message types that this service can act upon:

- LSRegisterRequest   - Given the name of a service and the metadata it
                        contains, register this information into the LS.
                        Special considerations should be given to already
                        registered services that wish to augment already
                        registered data.
- LSDeregisterRequest - Removes all or selective data about a specific service
                        already registered in the LS.
- LSKeepaliveRequest  - Given some info about already registered data (i.e. a 
                        'key') update the internal state to reflect that this
                        service and it's data are still alive and valid.
- LSQueryRequest      - Given a descriptive query (written in the XPath or
                        XQuery langugages) return any relevant data or a 
                        descriptive error message.

The LS in general offers a web services (WS) interface to the Berkeley/Oracle DB XML, a native XML database.

API

The offered API is not meant for external use as many of the functions are relied upon by internal aspects of the perfSONAR-PS framework.

init($self, $handler)

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 (DB XML). Finally the message handler loads the appropriate message types and eventTypes for this module. Any other 'pre-startup' tasks should be placed in this function.

needLS($self)

Stub function that would allow the LS to register with another LS. This is currently disabled.

cleanLS($self)

On some schedule the daemon will kick off a process to clean the LS (or any other service that happens to implement this function, i.e. dLS). This process will connect to the database, and check the timestamps of all registered data. Anything that is 'expired', i.e. hasn't been updated in the TTL for the data will be removed.

handleMessageParameters($self, $msgParams)

Looks in the mesage for any parameters and sets appropriate variables if applicable.

prepareDatabases($self, $doc)

Opens the XMLDB and returns the handle if there was not an error.

isValidKey($self, $metadatadb, $key)

This function will check to see if a key found in a request message is a valid key in the datbase.

handleMessage($self, $doc, $messageType, $message, $request)

Given a message from the Transport module, this function will route the message to the appropriate location based on message type.

lsRegisterRequest($self, $doc, $request)

The LSRegisterRequest procedure allows services (both previously registered and new) the ability to register data with the LS. In the case of previously registered services it is possible to augment a data set with new information by supplying your previously issued key, or change an existing registration (i.e. if the service info has changed) and subsequently un and re-register all data. Responses should indicate success and failure for the datasets that were registered. This function is split into sub functions described below.