Bionanny::Listener - Bionanny module for accessing logged records
use Bionnany::Listener;
my $bionanny =
new Bionnany::Listener
(-location => 'http://my.services.org/BionannyService');
print $bionanny->get;
A one-liner (using a default location and cheating by using directly a numeric constant):
perl -MBionanny::Listener \
-e 'print new Bionanny::Listener->get(-level, 1)'
Or:
perl -MBionanny::Listener \
-e 'print join ("\n", new Bionanny::Listener->get(-level, 1)'
This is a class whose instances can listen to any Bionanny service and produce its output in XML format.
A Bionanny service monitors usage of other Web services and keeps
stored information about their invocations. The Bionanny service is
(usually) itself a Web Service and Bionanny::Listener (and a
derived classes from it) uses SOAP protocol to get to the monitored
data. This may change later in order to enable additional access
protocols (such as a direct access to the local RDMB).
This Bionanny::Listener is the main class to be used by the end
users. It loads a real implementation of a particular access protocol
according to the argument -access. At the time of writing, there is
only SOAP protocol available:
-access => soap
This loads class the Bionanny::Access::soap manpage that is a real
implementation of all methods defined here (in
Bionanny::Listener. The Bionanny::Access::soap should not be
instantiated directly (use Bionany::Listener instead).
Look into the Bionanny::Access::soap manpage to find what additional (and protocol specific) arguments can be used in the constructor.
Martin Senger (support@bionanny.org)
This file is a component of the Bionanny project. Copyright Michael Niemi & Martin Senger. For details contact support@bionanny.org, or see http://www.bionanny.org/.
Parts were re-factored from modules available in Bioperl project. See copyright notices there.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This software is provided ``as is'' without warranty of any kind.
There are several predefined constants that can influence how much are resulting data cumulated. A Bionanny service recognizes three levels: services (which are individual Web services, distinguished by their endpoints), requests (represented by individual Web service operations), and finally level of individual logged records (when nothing is cumulated).
These constants are used in the get method as the
-level parameter. For example:
$listener->get (-level => $listener->CUMULATED_FOR_SERVICES);
A level indicating that the returned date should not be cumulated at all.
A level indicating that the returned data should be cumulated on a service level (meaning that all requests for a particular service are squeezed into one record).
A level indicating that the returned date should be cumulated on a request level.
And there are also few other constants defined in this module:
Used in the get method in parameter -from or -to (or both,
matter of fact) indicating that only records about started but not yet
finished requests should be collected.
The methods described in this documentation represent a public interface to Bionanny services.
my $obj = new Bionanny::Listener (@args);
It builds, populates and returns a new Bionanny::Listener
object. This is how it is seen from the outside. But in fact, it
builds, populates and returns a more specific lower-level access
object, for example Bionanny::Access::soap object. Which one, it
depends on the parameter -access. It returns undef on failure.
The recognized names in arguments @args are:
It indicates what lower-level module to load. Default value is
soap.
It specifies where to find a Bionanny service. The format and
contents of this argument is dependent on the -access argument.
For soap access it is a URL of a Bionanny Web Service. Default is
http://localhost:8080/axis/services/bionanny.
Other arguments can be given here as well - but they are recognized by
the lower-level (access) module (e.g. see Bionanny::Access::soap).
my $xml = new Bionanny::Listener(...)->get (@args);
This is the main method. It returns data (in XML) that had been collected by a Bionanny monitoring service. The returned data can be cumulated on the requested level. Data can also be selected in order to contain:
* only data from listed services
* only data from the requested period
* only data about still running requests
* only data matching requested metadata (TBD)
The recognized names in arguments @args are:
Can be any of the constants CUMULATED_FOR_REQUESTS, CUMULATED_FOR_SERVICES and NOT_CUMULATED. The default value is CUMULATED_FOR_REQUESTS.
Contains an array of service names whose data should be returned. By default data about all services are returned. The names should correspond to the services endpoints (but this will change in the future in order to allow also simplified names).
Specifies the starting time of a requested period. If zero or undef
then data starting from the beginning (including oldest) are
returned. If it matches with the literal 'now' (case-insensitive)
then it returns data only about still running requests (and the -to
argumen, if any, is ignored). Or, it can be a pure number (minus sign
allowed) which means that the starting point is this number of
millisecond from now. Or, the number can be accompanied by a last
letter, indicating a unit for the number. The letter can be 's' for
seconds, 'm' for minutes, 'h' for hours, 'd' for days, 'w' for weeks
and 'M' for months.
Specifies the ending time of the requested period. It can have the
same formats as -from.
Contains an array of metadata names. Only data corresponding with these metadata are included in the result. (Not yet implemented.)
If true the date fields in the returned XML will be more readable,
e.g. Tue Apr 27 08:53:03 2004. Otherwise, they will contain the
number of millisecond from the Epoch.
my %list = new Bionanny::Listener(...)->available_services;
It returns a hash where keys are endpoints of services a connected monitoring service has some data about, and values are the simplified (display) service names (usually the last part of the endpoint).
my @list1 = $listener->available_metadata; my @list2 = $listener->available_metadata (@service_names);
It returns a list of names of all available metadata, or only names of metadata recorded for given services. If none of the given service names exists then an empty array is returned.