Installation and building   

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:

At the time of writing, it was tested it with JDK 1.4. But the latest JDK 1.5 is an obvious test target soon.
Apache Tomcat servlet engine
Actually, it can be any servlet container (such as JBoss) - but I have tested deployment only with Apache Tomcat.
Apache Axis SOAP toolkit
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):

  1. You need to have mySQL installed (from this time you also know the database's root password).
  2. 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.

  3. The run-time access to the database is granted by a set of properties defined in your file. Create this file by copying, 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.
  4. 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:
    ./ 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 will enter the game).

The Ant targets (or tasks) are invoked by calling either (build.bat on MS-Windows), or (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:

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:

The file 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:

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

Usually, however, the only properties you may need to set, are:

catalina.home = /where/is/your/tomcat
jdbc.passwd = what is your password to mySQL Bionanny database

and a very recommended one (if you have installed jikes on your machine):

build.compiler = jikes

Having explained Ant properties, we may finally go and see what actually one can do with the Bionanny Ant...

  Available Ant targets

You can always see the most recent version of available Ant's targets by typing:

./ -projecthelp

Or, if you have installed an Ant Visualizer (visant), you can see it graphically.

The normal build targets are:

./ compile
Compile all source code (default). It also creates run scripts in build/run directory. They are used for running various clients.
./ docs
Generate all documentation. All, except for the Perl modules documentation - for that call ./ perldocs. This is separated because not all users will be using Perl.
./ jar
Create jar file with Bionanny classes.
./ clean
Remove most of the generated files. You can also remove all third-party libraries by calling ./ cleanall.
./ all
Clean, compile, jar and generate docs.
./ 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:


Then you can copy things to your local Tomcat:

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* 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:

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


Martin Senger, Mike Niemi
Last modified: Mon Apr 11 00:40:58 2005