This guide describes what can be done after you check out Bionanny
from the CVS. Most of the tasks described here are invoked using the
Java's wonderful tool Ant (which is part of the Bionanny CVS module - you
do not need to download anything else).

Before going further, let's check what components are not
part of the Bionanny distribution.

System requirements

Before you start to use Bionanny you need to have, or to install,
few (obvious) things:

This is a set of Java libraries that do all the SOAP stuff. You
need to install these libraries into your Tomcat (or into whatever
servlet engine you are using). Follow the Apache Axis
documentation for that.

A mySQL database is used to store monitored data. At the time
of writing, this is the only way how to keep and retrieve
data. In the future, someone may write a new implementation storing
data in other way (flat files, dbm, or whatever). The mySQL
database must be initiated to create a database instance for Bionanny
and to grant proper access privileges - see below how o do it.

Optionally, Perl

Bionanny includes several Perl clients that can retrieve and
display monitored data. If you want to use them (recommended if your
OS allows it) you will need also few additional Perl modules:
SOAP::Lite (which itself has a lot of dependencies),
Error, GD, GD::Graph.

And, obviously, you need some Web Services that can be monitored

Well, not really - the Bionanny provides a Sleeping Web Service
that can be used for testing and for creating huge amount of requests
(see about it a Sleep Generator
Guide).

How to create a Bionanny database

A mySQL database keeps (and provides) the logged data. Here is how
to setup your local Bionanny database (this is probably the only task
that is not part of Bionanny Ant - should we put it there? - because
it requires to type a mySQL's root password):

You need to have mySQL installed (from this time you also know
the database's root password).

You need to grant privileges to use the database:
Let's assume that you wish to use the user name
bionannyuser with the password bionanny is for
Gods. The database is named bionanny (this name is
already hard-coded in the src/etc/sql/createTables.sql that
is used in the next step - change it there if you wish a different
name). Now you can type:

mysql -u root -p
Enter password: <enter mySQL root password>
mysql> grant all on bionanny.* to bionannyuser@"%"
mysql> identified by "bionanny is for Gods";
mysql> grant all on bionanny.* to bionannyuser@localhost
mysql> identified by "bionanny is for Gods";
mysql> quit

Note that the default user name is also bionanny - the
example above uses a different name just to distinguish it from the
database name. If you use the default user name you do not need to use
the property jdbc.user in the run-time - see more below about the run-time properties.
Note that this step does not create a database instance, it just
creates permissions to use it.

The run-time access to the database is granted by a set of
properties defined in your build.properties file. Create this
file by copying build.properties.templates, and edit it. See
details what could/should be edited there (the properties related to
the mySQL database starts with jdbc.).
If you use default values the only property you need
to put there is jdbc.passwd with your password to the
Bionanny database.
Anyway, the whole business dealing with properties is described
(perhaps in more details) below.

The last step is to create all necessary Bionanny database
tables (actually to create a Bionanny database instance). You can
repeat this step anytime - for example, when you wish to remove all
logged data from your Bionanny database. That's why there is also an
Ant target for it.
The database creation is done by an SQL script
src/etc/sql/createTables.sql. This script is not a shell
script that can be started form your terminal window. You need to
source it from the mysql program, after granting proper
privileges.
But the easiest (and recommended way) is to use Ant for it by
invoking:

./build.sh db-create

How to use Ant in Bionanny

Apache Ant is a Java-based build tool to do things. And do them
independently on your local environment (that's where your file
build.properties will enter the game).

The Ant targets (or tasks) are invoked by calling either
build.sh (build.bat on MS-Windows), or
build-dev.sh (build-dev.bat on MS-Windows) script. Because
usually you use the latter, the examples below use the -dev
form.

What is the difference between -dev script and without
-dev script? Remember that:

You can use build.sh (build.bat) script
anytime, but

You must use it the first time (because it gathers all
third-party libraries needed for compilation). Otherwise

You may use build-dev.sh (build-dev.bat) which
is slightly faster because it does not attempt to fetch libraries from the Internet.

Why not just to type ant as usual? Because it would
invoke your own Ant - which may be of a different version than the Ant
used by Bionanny, and because it does not have one or two additional
tasks that Bionanny's Ant comes with. Be aware that from the same
reason the building scripts do not use the environment
variable ANT_HOME even if it is set.

You may (and should) also influence the Ant work by setting
various properties. It brings us to the next section...

Configuration properties

Whatever Ant does, it always can be configured by various
properties. They have format of Java properties which means that
they are simply represented by name-value pairs. They can be
set in two ways:

They can be set (use) directly on the command line (when Ant is
being invoked), using -Dname=value syntax. For example:

./build-dev.sh -Dbuild.compiler=jikes compile

Or (a more usual way), they can be put into a
build.properties file where Ant reads them from.

The file build.properties can be put either directly in
your bionanny directory, or in your home directory (the
latter is suitable if you wish to share some properties with other
Java projects).

So what are these properties about? General rules about properties
used by Ant are:

If you need something that is outside of the Bionanny
CVS local copy you need to specify a property for it
(e.g. the location of your Tomcat is definitely outside of your
Bionanny directory).

If you wish to change the default Ant behavior you may
need to define your own property (e.g. names of testing services to be
deployed). (By the way, the Bionanny Ant default behavior, and all its
targets/tasks are conserved in the build.xml file but its
description is beyond the scope of this guide.)

All (reasonable) properties are described in the
build.properties.template file that has always the most
recent details. Here is its snapshot.

Compile all source code (default). It also creates run
scripts in build/run directory. They are used for
running various clients.

./build-dev.sh docs

Generate all documentation. All, except for the Perl modules
documentation - for that call ./build-dev.sh perldocs. This
is separated because not all users will be using Perl.

./build-dev.sh jar

Create jar file with Bionanny classes.

./build-dev.sh clean

Remove most of the generated files. You can also remove
all third-party libraries by calling ./build-dev.sh
cleanall.

./build-dev.sh all

Clean, compile, jar and generate docs.

./build-dev.sh wsdl

Generate WSDL description of Bionanny Web service. You can set
property bionanny.endpoint to a location (URL) where the
Bionanny service will be visible to the word.

The summary is that after checking out the Bionanny CVS module you
should gather all third-party libraries and compile everything by
typing:

./build.sh

Then you can copy things to your local Tomcat:

tomcat-populate

It takes all necessary jar files and copy them where
Tomcat can find them. This does not need to have Tomcat
running - but if it does it usually needs to restart it
after that (restarting is not done automatically by this
target).

deploy-monitor (and undeploy-monitor)

A Bionanny monitor is a handler that actually does the
monitoring of incoming requests. But just have it deployed
does not cause any monitoring - there must be some Web
Services that have been deployed in a chain (flow) with
this monitor handler. For more see the architecture guide.

deploy-bionanny (and undeploy-bionanny)

A Bionanny service is a core Web service of the whole
project. It is called by a Bionanny monitor to store/log
requests flowing through the monitor. It can, however,
log also data monitored elsewhere. And it also provides
stored data back.

deploy-sleepers (and undeploy-sleepers)

Sleepers are just testing Web Services that sleep for
a while before they give back their response. They all are
implemented by the same class - but you can have many of them
under many different service names. By default there are six
of them deployed (you can change the names and sleeping
characteristics by setting properties service.call.* and
service.acall.* - see how to use a sleep generator).

deploy (and undeploy)

And finally, this target deploys everything mentioned above.

There are also targets dealing with your local mySQL database.
The database is used by the Bionanny service to store monitored data:

db-create

It removes all data and re-create the database from the
scratch. But it does not add (grant) any necessary user
privileges (see above how to do that -
and you need that only for the first time).

db-clean-running

It removes records indicating that a request started but
has not been finished. Usually, these records are pending
because of some malfunctions or crashes.

Few other, but important, targets for adding Bionanny monitors to
existing and already deployed services is descrived in the monitor guide.