NAME

Bionanny::Listener - Bionanny module for accessing logged records


SYNOPSIS

  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)'


DESCRIPTION

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.


SEE ALSO

http://www.bionanny.org


AUTHOR

Martin Senger (support@bionanny.org)


COPYRIGHT

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.


DISCLAIMER

This software is provided ``as is'' without warranty of any kind.


CONSTANTS

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);

NOT_CUMULATED

A level indicating that the returned date should not be cumulated at all.

CUMULATED_FOR_SERVICES

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).

CUMULATED_FOR_REQUESTS

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:

ONLY_RUNNING_SERVICES

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.


METHODS

The methods described in this documentation represent a public interface to Bionanny services.

new

  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:

-access

It indicates what lower-level module to load. Default value is soap.

-location

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).

get

  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:

-level

Can be any of the constants CUMULATED_FOR_REQUESTS, CUMULATED_FOR_SERVICES and NOT_CUMULATED. The default value is CUMULATED_FOR_REQUESTS.

-snames

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).

-from

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.

-to

Specifies the ending time of the requested period. It can have the same formats as -from.

-mnames

Contains an array of metadata names. Only data corresponding with these metadata are included in the result. (Not yet implemented.)

-humandates => 1

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.

available_services

  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).

available_metadata

  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.