BionannyClient Guide (Bionanny)

BionannyClient Guide

The Java program org.bionanny.client.BionannyClient is a command-line application that serves two purposes:

To invoke various parts of the Bionanny software in order either to test/debug them, or actually use them, and
To show an example of the code how to invoke/use Bionanny software.

There is also a Perl client (called bionanny.pl) providing similar features - except it always needs a running Bionanny Web Service (it does not know how to access local database directly). And there is also a set of cgi-bin scripts providing access to Bionanny features using a Web browser. The advantage of these Perl clients is that they can create a graphical representation of the Bionanny data.

But back to the Java BionannyClient:

Usage

The BionannyClient is started by:

build/run/run-bionanny-client [options]

. build/run/source.me.sh (or: source build/run/source.me.csh)
java [properties] org.bionanny.client.BionannyClient [options]

Use the latter if you need to set some Java properties (but the script build/run/run-bionanny-client already has some of the below described properties - check the script - they were put there by Ant when you had been building Bionanny).

To set the following properties is necessary only if you want to log or use Bionanny data locally (to and/or from a local mySQL database), without using a Bionanny Web Service. The properties are used only if you do not specify a Bionanny Web Service's endpoint (see below an option -e).

-Djdbc.url=jdbc:mySQL://localhost/bionanny
-Djdbc.user=bionanny
-Djdbc.passwd=bionanny_password
-Djdbc.driver=org.gjt.mm.mysql.Driver

Usually only the jdbc.passwd is needed, others will use reasonable defaults (as shown above). Be aware that you also need to initiate your local database before the first usage - e.g. by calling an Ant target db-create (see more in the build guide).

Options

Use option -help to get (perhaps more accurate) list of all options.

The options fit into several categories:

Where to log data and where to get data back from:

-e <endpoint> URL of a Bionanny Web Service (e.g. http://localhost:8080/axis/services/bionanny)

How to log data:
Note that data do not need to come only from this client (actually, mostly they, indeed, do NOT come from this client, at all), they can be logged from various sources (mostly by using Bionanny's MonitorHandler interceptor). This feature is mostly here for testing - so you can create some records in the local mySQL database before you deploy and call any monitored Web Service.

-log <file> File with records to be logged.
An example of such file is shown in build/data/logging.input. Each line (except comment lines starting with a #, and blank lines) represents a record to be logged. It consists of the words separated by commas. The fields are:

service endpoint
service name
request ID
record ID (fill it only when recording twice the same event: start and end)
sender
started time (in millis, fill it only when recording a still running service)
elapsed time (in millis)
metadata name 1
metadata value 1
metadata name 2
metadata value 2
...

How to clean logged data (this feature is not available from a Bionanny Web Service but only when accessing a local database):

-cleanrunning It removes records that indicate that a request started but has not been finished; use this to remove pending records - useful after something crashed or was badly configurated. You can also use this together with an -s option to clean only after selected services.

List various (previously logged) data:

-ls Get list of all available service names.

-lm Get list of all available metadata names.

-lM <service-name> Get metadata names only for the given service.

How to get logged data back:

-get Get recorded data back.
Use this option if you do not have any other query options (such as -s). If you use any of the query options, it implies also -get by default (unless a -cleanrunning is given).
The following query options can limit returned data to a subset (if more of them given, they are combined by logical AND).

-s <service-name>
[,<service-name>...] Get back data only about the given services. The service names are from the list returned by the -ls option.

-f <from-date Get back data recorded after <from-date>.
The format of <from-date> is yyyy-MM-dd HH:mm:ss (you can omit any ending part - at least I think so).
Or, it can be a number (with or without a minus sign) meaning "data recorded during the last period given, ending now". The number is in milliseconds unless it ends with one of the following characters:

s for seconds
m for minutes
h for hours
d for days
w for weeks
M for months

Examples:
-f 2004-04-30 14:10:00 -f -20000 -f -3d -f -4w

Or, it can be a word now (case-insensitive) meaning "only still running requests".

-f <to-date Get back data recorded before <to-date>.
The format is the same as for <from-date>. For example: -f -2d -t -1d means get data from a day before yesterday.

-m <metadata-name>
[,<metadata-name>...] Get back only data that have been recorded with at least one of the given metadata names. Metadata names can be obtained using the -lm. option.
(not yet implemented

How many details to get back (by default all details are returned):

-cs Return data cumulated on the service level.

-cr Return data cumulated on the request level.

What format to get data back in:
This is particularly useful for the non-Java clients that would otherwise need to code their own data encoders to de-serialize returned data type (which is, in Java speak, org.bionanny.shared.CollectedData).
If no format given, the returned org.bionanny.shared.CollectedData are printed in a sort-of human readable form.

-x Get data in XML.

Martin Senger, Mike Niemi

Last modified: Thu Apr 7 23:47:40 2005

Where to log data and where to get data back from:
-e <endpoint>	URL of a Bionanny Web Service (e.g. http://localhost:8080/axis/services/bionanny)
How to log data: Note that data do not need to come only from this client (actually, mostly they, indeed, do NOT come from this client, at all), they can be logged from various sources (mostly by using Bionanny's MonitorHandler interceptor). This feature is mostly here for testing - so you can create some records in the local mySQL database before you deploy and call any monitored Web Service.
-log <file>	File with records to be logged. An example of such file is shown in `build/data/logging.input`. Each line (except comment lines starting with a #, and blank lines) represents a record to be logged. It consists of the words separated by commas. The fields are: service endpoint service name request ID record ID (fill it only when recording twice the same event: start and end) sender started time (in millis, fill it only when recording a still running service) elapsed time (in millis) metadata name 1 metadata value 1 metadata name 2 metadata value 2 ...
How to clean logged data (this feature is not available from a Bionanny Web Service but only when accessing a local database):
-cleanrunning	It removes records that indicate that a request started but has not been finished; use this to remove pending records - useful after something crashed or was badly configurated. You can also use this together with an `-s` option to clean only after selected services.
List various (previously logged) data:
-ls	Get list of all available service names.
-lm	Get list of all available metadata names.
-lM <service-name>	Get metadata names only for the given service.
How to get logged data back:
-get	Get recorded data back. Use this option if you do not have any other query options (such as `-s`). If you use any of the query options, it implies also `-get` by default (unless a `-cleanrunning` is given). The following query options can limit returned data to a subset (if more of them given, they are combined by logical AND).
-s <service-name> [,<service-name>...]	Get back data only about the given services. The service names are from the list returned by the `-ls` option.
-f <from-date	Get back data recorded after <from-date>. The format of <from-date> is `yyyy-MM-dd HH:mm:ss` (you can omit any ending part - at least I think so). Or, it can be a number (with or without a minus sign) meaning "data recorded during the last period given, ending now". The number is in milliseconds unless it ends with one of the following characters: `s` for seconds `m` for minutes `h` for hours `d` for days `w` for weeks `M` for months Examples: -f 2004-04-30 14:10:00 -f -20000 -f -3d -f -4w Or, it can be a word `now` (case-insensitive) meaning "only still running requests".
-f <to-date	Get back data recorded before <to-date>. The format is the same as for <from-date>. For example: `-f -2d -t -1d` means get data from a day before yesterday.
-m <metadata-name> [,<metadata-name>...]	Get back only data that have been recorded with at least one of the given metadata names. Metadata names can be obtained using the `-lm`. option. (not yet implemented
How many details to get back (by default all details are returned):
-cs	Return data cumulated on the service level.
-cr	Return data cumulated on the request level.
What format to get data back in: This is particularly useful for the non-Java clients that would otherwise need to code their own data encoders to de-serialize returned data type (which is, in Java speak, `org.bionanny.shared.CollectedData`). If no format given, the returned `org.bionanny.shared.CollectedData` are printed in a sort-of human readable form.
-x	Get data in XML.