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.

The following is a brief outline of the procedures:

    Does MD have a key
    Y: Update of registration, Is there a service element?
      Y: Old style 'clobber' update, pass to lsRegisterRequestUpdateNew
      N: New style 'append' update, pass to lsRegisterRequestUpdate
    N: This is a 'new' registration, pass to lsRegisterRequestNew
    

lsRegisterRequestUpdateNew($self, $doc, $request, $metadatadb, $m, $d, $mdKey, $service, $sec)

As a subprocedure of the main LSRegisterRequest procedure, this is the special case of the 'clobber' update. Namely there is data for a given key in the database already (will be verified) and the user wishes to update the service info and delete all existing data, and replace it with new sent data. This essentually amounts to a deregistration, and reregistration.

The following is a brief outline of the procedures:

    Does service info have an accessPoint
    Y: Remove old info, add new info
    N: Error Out

lsRegisterRequestUpdate($self, $doc, $request, $metadatadb, $m, $d, $mdKey, $sec)

As a subprocedure of the main LSRegisterRequest procedure, this is the special case of the 'append' update. Namely there is data for a given key in the database already (will be verified) and the user wishes to add more data to this set. The key will already have been verified in the previous step, so the control info is simply updated, and the new data is appended.

lsRegisterRequestNew()

As a subprocedure of the main LSRegisterRequest procedure, this is the special case of the brand new addition. We will check to be sure that the data does not already exist, if it does we treat this as an 'append' update.

The following is a brief outline of the procedures:

    Does service info have an accessPoint
    Y: Is the key already in the database
      Y: Is the service info exactly the same
        Y: Treat this as an append, add things and update key
        N: Error out (to be safe, ask them to provide a key)
      N: Create a key, add data
    N: Error Out

lsDeregisterRequest($self, $doc, $request)

The LSDeregisterRequest message should contain a key of an already registered service, and then optionally any specific data to be removed (absense of data indicates we want removal of ALL data). After checking the validity of the key and if possible any sent data, the items will be removed from the database. The response message will indicate success or failure.

The following is a brief outline of the procedures:

    Does MD have a key
    Y: Is Key in the DB?
      Y: Are there metadata blocks in the data section?
        Y: Remove ONLY the data for that service/control
        N: Deregister the service, all data, and remove the control
      N: Send 'error.deregister.ls.key_not_found' error
    N: Send 'error.ls.deregister.key_not_found' error

lsKeepaliveRequest($self, $doc, $request)

The LSKeepaliveRequest message must contain 'key' values identifying an already registered LS instance. If the key for the sent LS is valid the internal state (i.e. time values) will be advanced so the data set is not cleaned by the LS Reaper. Response messages should indicate success or failure.

The following is a brief outline of the procedures:

    Does MD have a key
      Y: Is Key in the DB?
        Y: update control info
        N: Send 'error.ls.keepalive.key_not_found' error
      N: Send 'error.ls.keepalive.key_not_found' error

lsQueryRequest($self, $doc, $request)

The LSQueryRequest message contains a query string written in either the XQuery or XPath languages. This query string will be extracted and directed to the XML Database. The result (succes being defined as actual XML data, failure being an error message) will then be packaged and sent in the response message.

The following is a brief outline of the procedures:

    Does MD have a supported subject (xquery: only currently)
    Y: does it have an eventType and is it currently supported?
      Y: Send query to DB, prepare results
      N: Send 'error.ls.query.eventType' error
    N: Send 'error.ls.query.query_not_found' error

Any database errors will cause the given metadata/data pair to fail.

lsKeyRequest($self, { doc request metadatadb })

The LSKeyRequest message contains service information of a potentially registered service. If this service is registered, the lsKey will be returned otherwise an error will be returned.

Any database errors will cause the given metadata/data pair to fail.

SEE ALSO

Log::Log4perl, Time::HiRes, Params::Validate, Digest::MD5, perfSONAR_PS::Services::MA::General, perfSONAR_PS::Services::LS::General, perfSONAR_PS::Common, perfSONAR_PS::Messages, perfSONAR_PS::DB::XMLDB, perfSONAR_PS::Error_compat

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: LS.pm 1877 2008-03-27 16:33:01Z aaron $

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

All rights reserved.