HOME > Community > Projects > xtest

XTest Database Feeder

Version: 1.0
Last Update: 18-th May, 2006
Author: Martin Brehovsky

Abstract: This document describes a part of Test framework which handles storing results from Publishing Server to database.

What is this document for?

This document is intended for test administrators who need to upload results from several Publishing Server to Central Database. There is usually one instance of dbFeeder for one instance of relational database.

Overview

Database Feeder (dbFeeder) is responsible for storing test results submitted by one or more Publishing Engine Servers to a relational database, where the results can be further processes and analyzed. Please note, implementation of a database front end called 'Central Database' is currently not open sourced.

Before Running dbFeeder

Before running publishing server, make sure you have the following:

JRE or JDK, at version 1.4.
Ant version 1.4 or greater
HTTP server and directory where results from testing machines together with summary pages will be stored.
Exported directory (via NFS for Unix machines, via SMB for Windows machines) where testing machines will store test results. Please note, this directory has to have read/write access either for users running tests on testing machines or the user running publishing server.

Building dbFeeder

dbFeeder is currently part of Publishing Engine Server, so if you have built PES, you have already built dbFeeder as well. For more information look at "Building PES" part of Publishing Engine Server document.

Configuring dbFeeder

Similarly as Publishing server, dbFeeder can be configured via XML configuration file. DTD file with explaining comments for the configuration file will be available later. The following lines contain a simple example of such a config file (you can use it as a template for your own configuration file).

<?xml version="1.0"?>
<PESdbFeederConfig loggingLevel="WARNING" deleteAge="20">
    <workdirs>
      <incoming>/mytools/dbfeeder/upload</incoming>
      <work>/mytools/dbfeeder/work</work>
      <invalid>/mytools/dbfeeder/invalid</invalid>
      <crash>/mytools/dbfeeder/crash</crash>
    </workdirs>
    <mail loggingLevel="WARNING">
      <smtpHost>smtp.netbeans.org</smtpHost>
      <from>pes@netbeans.org</from>
      <to>pes-admin@netbeans.org</to>      
    </mail>
    <database>
       <username>xtest</username>
       <password>xtest</password>
       <driverClass>oracle.jdbc.driver.OracleDriver</driverClass>
       <URL>jdbc:oracle:thin:@oracle-database.netbeans.org:1521:xtest</URL>
    </database>
</PESdbFeederConfig>

The main element 'PESdbFeederConfig' contain two attributes:

loggingLevel - it says what level dbFeeder uses for writing out information on a console (default is SEVERE, usually there is no reason to change it, this example is for demonstration only).
deleteAge - defines how many builds should be kept in database. Older builds beyond deleteAge threshold will be deleted.

Subelement 'workdirs' defines via it's subelements necessary working directories for dbFeeder:

incoming - where are the reports uploaded by Publishing Engine Servers
work - working directory of dbFeeder
invalid - directory where are put files from incoming directory which are not valid
crash - directory where are put working files found in the case of dbFeeder failure (this should help to recover from it, because no data should be lost)

Subelement 'mail' defines requires fields for sending notification emails. The loggingLevel says which logging level is used for sending emails (again default is SEVERE and there is usually no reason to change it, this example is for demonstration only). The subelements are:

smtpHost - host which serves as your smtp server
from - address which is used as an user who send the email
to - address to which the notification is sent

Subelement 'database' defines JDBC connection parameters for a database to which results are stored. Subelements meaning is:

username - user name of the database user
password - user's password
driver - class of a JDBC driver used to connect to the database
URL - JDBC URL connection string

When done with the configuration file, you will also need to configure dbFeeder's shell script (available in CVS, at nb_all/xtest/bin/xtest-dbfeeder.sh), which runs periodically the dbFeeder's main program. Here you will need to set several variables:

DBFEEDER_HOME - directory where is your home of PES/dbFeeder
DBFEEDER_CONFIG - path to your dbFeeder configuration file
JAVA_HOME - directory where JDK 1.4 is installed
JDBC_DRIVER - path to jar with JDBC driver used for connection to the database

Running dbFeeder

When everything is properly configured, you can run PES via supplied shell script, which is available in CVS at nb_all/xtest/bin/xtest-pes.sh (please don't forget to properly set all required variables) . The script can be run in the following ways:

'xtest-dbfeeder.sh start' - runs dbFeeder in background
'xtest-dbfeeder.sh run' - runs dbFeeder in foreground
'xtest-dbfeeder.sh stop' - stops the server (if running) in a gentle way (the server will agree on the end), so it might take even a couple of minutes to finish it's work
'xtest-dbfeeder.sh kill' - kills unconditionally the server - this command is not recommended for general use, unless this is the only way to stop it.