perfsonar development work

[ulisses <>]

Hi all

I'm sorry I could not send this before I did an small documentation about 
what are
the interactions of the topology server.

I think I did not forgot your guidelines from previous conf.

I still have to send to jason the sql to xml mapping and a new
example of the messages.

can you take a look at this to see if something is too bad?

Thanks

        Ulisses





### Functionality

The functionality provided by this messages is determined by the required 
interactions 
specified in the Topology Service resources page.

see http://wiki.perfsonar.net/jra1-wiki/index.php/Topology_Service_resources

Basically the funcionality required is

- register in the Lookup Service in order to allow the Tops to be located by 
clients
- download of the topology database of a domain or parts of it
- allow registration of clients in order to be notified when a database 
change occurs.

### Client/Server interactions (Message exchange) 

There are two types of message exchanges in the Tops, 

The expected interaction is that the client requests full or partial database 
download (currently partial download is supported) of a specified time frame 
and optionally
requests to be informed in case of a change of the specified part of the 
database. The 
client also specifies a key in the request. This is a "Database download 
request triggered 
by client".

In case the client also wants to be notified in case of a database change the 
client will also
include a notifier URL in the former request, that will be used by the server 
in order
 to send a perfSonar message later in a "Database download triggered by 
server".

- Database downloads requests triggered by client. The client requests full 
or partial database
  download but currently partial download is supported. (see 
tops-messages.png: message exchange
  type #1).

  Database downloads have currently four parameters specified in a single 
metadata block:

     - key: an identifier of the request specified by the client, server's
            response has to include the same key. It has an opaque
            meaning to the server.

     - domain_id: the domain for which the selection is wanted. Currently
            Topology service only supports one domain. This parameter avoids
            about to what domain_id is the information the information was 
            requested and allows support for multi domain topology services.

     - Time: used to retrieve historical information, the request specifies 
            the request specifies the date for which download the topology
            information.

             A value of "now" means current topology database information.

     - ttl: the desired value of the time to live of the query, in seconds.

            This is used to provide updated information to the client 
            when the database changes. 

            - A value of zero means download the information only once. 
            - A value greater than zero means that the client wants 
              to register to be notified when then information is updated 
              for the database or part of it that is specified. 

            The server will reply with the effective ttl. The server
            will enforce a value that will be equal or less than the specified
            value (even zero), the client will be informed in the reply.

            When a request is registered with a ttl equal to zero, the 
database
            is included in the response of the request. 

            When the ttl > 0 the initial database download is also included in
            the response, if there are any modifications, the dabase download
            is done with a new http request done through the url specified
            with the "notifier" parameter, described next.

    - notifier: This parameter is only used when the client specifies a ttl 
greater
            than zero. It speciries an url of a perfsonar service that the 
server will
            use to inform when the specified database is modified. 
Disambiguation
            of several notifiers is satisfied by the use of different keys 
specified
            by the client.

            Notifications are xml files like responses, that is:

            - no incremental updates are done
            - all elements of the specified selection (or full dabase if 
applies)
              is sent each time any element of the specified selection (of 
the whole
              database if applies) is modified.

            Notifications are synchronous. The client is notified as soon as
            possible when modification is done. In other words, when the 
client is 
            informed the information is meant to be valid.

            CAVEAT: what happens if Time is not "now" and ttl is not zero?

            it is not clear why the client will be more interested. Once
            the server replies with the database information as of the 
            specified time, when/what information should be triggered the 
            client with?

            There are three options:

            a) inmediately send a server triggered database download of
               the current database because the data has been modified since 
               it could have been modified since then.

               This could be useful to allow a client to download a topology
               of an specified time and then having without further messages
               the current image of the database. 

               It can be expensive to determine if there has been a change.

               This also opens the question, should be the client be informed
               always? only if a database has been produced?

            b) download the database information and then be notified if 
               when a modification to current database is produced. Because 
               state may be different already, it doesn't seem to be very 
               useful:

               T(1000)                 T(now = 1500)            T(2000)
                                             ^                     |
                                             |                     |
                                             |                     v
                                  request database for      Get notification 
                                           T = 1000             of change

            c) do not contemplate notifications in case of Time is not equal
               to "now".

            For now I will choose opcion c) because of simplicity and 
notifier and
            an error will be triggered in this case.

- Database downloads triggered by server. This happens when when a 
modification is done 
and the client previously wanted to be notified to download the information 
if the selection 
of the database is done.  (see tops-messages.png: message exchange
 type #2).

### Database partial selection or full download

Currently only full database downloads are implemented. 

Partial database downloads are specified in a separate metadata block. That 
is,
for a single request one (parameters) or two metadata blocks (the second 
for selection of the part of the database) are used.

Full database downloads are when there is no metadata block that specifies a 
selection
of the database.

About partial downloads. Because:
              
    1) we don't use an xml database that supports xquery/xpath
    2) xml to sql translation of queries is not easy

When implemented, the most probable is that we will allow only a restricted 
type 
of partial downloads. Selection of the database will be made with template 
xml file.

Attachment: tops-messages.png
Description: PNG image