Build Guide (Bionanny)

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:

Java: 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.
mySQL: 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.

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:

./build-dev.sh -projecthelp

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

The normal build targets are:

./build-dev.sh compile: 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.

Next...

Martin Senger, Mike Niemi

Last modified: Mon Apr 11 00:40:58 2005