NAME
    rgmacomplete - Adaptation layer of GlueDomains to R-GMA

SYNOPSIS
    use lib "GlueDomains/rgmacomplete";

    Creator:

    $rgma=rgmacomplete::<characteristic>Tools->new($ns);

    Queries:

    $rgma->insert($observation);
    $observation=$rgma->selectLast(%criteria);

DESCRIPTION
        This package implement a few basic functions to store observations
        into an R-GMA GIS, using the domains topology recorded into the
        GlueDomains structure. These are implemented as a set of classes,
        each for one of the characteristics (see below for a list of
        available characteristics). Each class implements an R-GMA producer
        of type latest: in essence, only the last observation is available
        through this producer.

        The name for each class is obtained appending the string Tool to the
        name of the characteristic. So that the rgmacomplete class
        corresponding to RoundTripDelay is RoundTripDelayTools.

        Each object of this class is bound to a NetworkService and to a
        specific characteristic.

        The new method returns a new object of the desired class, that will
        be used in successive insert or selectLast operations. It takes as a
        parameter a NetworkService object obtained through GlueDomains. It
        dies in case of problems, with a diagnostic on stderr (errors can be
        catched using b<eval>).

        The insert method publishes an observation using the appropriate
        class. It takes as parameters a rgmacomplete object that implements
        the producer, and the observation. Preferred syntax is

        $rgma-insert($observation)>

        In case of problems it dies with a diagnostic on stderr.

        The selectLast method returns just one observation satisfying the
        criteria passed as parameter. It takes as parameters the
        rgmacomplete object that implements the producer, and a hash
        representing the criteria: each element of the hash is composed by a
        key, that corresponds to a characteristic appropriate for that
        observation, and by a value for this characteristic. The returned
        observation (if any), must match these values. If there are no
        matching observations available, returns undef.

Discussion
        Although very limited, this design is overall reasonable.

        Limiting the access to the last observation does not allow
        statistical analysis and predictions. However, applications (or
        mediators) that want to collect historical data may query the
        producer frequently: this will be improved in the future,
        introducing Stream producers.

        The selectLast returns just one observation, selected by "equality":
        this seems to be a strong limit, but allows an early
        experimentation. We plan to improve the prototype on this side, when
        needed.

Example
         #!/usr/bin/perl -w
         use strict;
         use lib "GlueDomains";
         use lib "GlueDomains/rgmacomplete";
         use GlueDomains;

         my $ns=NetworkService::new("fromheretothere","here","there","besteffort");
         my $rgma=rgmacomplete::RoundTripDelayTools->new($ns);

         my $observation=
           RoundTripDelay->new($ns->{id},'myping',70,20202020,0.01,0.05,0,5);
         $rgma->insert($observation);

         my $resobs=$rgma->selectLast({'tool' => 'myping','packetSize' => 70});

         ( defined $resobs ) || die;
         foreach my $field (keys %$resobs) {
            print "$field = $resobs->{$field}\n";
         }

TODO
    improve code robustness (how to test that "new" fail?)
    use streamProducers instead of latestProducers (and write mediators...)
    introduce GGF terminology for characteristics and attributes