You must have an extension to your web server that allows it to run
servlets that conform to the specification.
JavaMail - mail.jar
The mail daemon, which processes emailed bug reports, utilizes JavaMail,
as does the DBI when emailing notices of re-assignment or or modifications.
Java Activation Foundation (JAF) - activation.jar
The mail daemon, which processes emailed bug reports, utilizes JavaMail,
as does the DBI when emailing notices of re-assignment or or modifications.
Syslog - syslog.jar
A Java syslog client package that allows us to log messages. This is
currently used only by the BugRat email processor program, not by any
of the servlets. Thus, you only need this if you run the email filter.
All of these JAR files are included in the WEB-INF/lib directory of
the WAR distribution file.
CURRENT BUGRAT USERS
BE CERTAIN TO READ THE RELEASE NOTES!
Several changes have been made to BugRat that will affect your database.
Specifically, several name changes were made to tables and fields. I hope
you will not have too much trouble making these changes to your existing
database. Furthermore, object ids are no longer generated using MySQL's
autoincrement feature. They are now managed by BugRat. This means that
you will need to run one of the Admin commands before you start using
the database. This will generate the id table that BugRat needs.
IF YOU DO NOT READ THE RELEASE NOTES, YOU WILL BE VERY SAD!
If you are creating a brand new BugRat database using the schemas included
with this release, then these changes obviously do not affect you.
Also note that there are new properties defined in BugRat to make it
more flexible. You should review the properties defined in the file
'sql/defproperties.sql' to see if there are any new properties that
you want to define in your database. Use the admin property edit
commands to edit these, or use your favorite SQL tool.
THE SUMMARY
Review ReleaseNotes-2.5.html
Current users of BugRat need to note that there were a couple of
name changes in the database schema. This was done to support other
databases, which reseserved names that BugRat was using. These name
changes are itemized in the release notes. I apologize for this, but
I really wanted to support as many databases as possible. Otherwise,
the only real difference is the upgrade to the Servlet 2.2 API, which
is the new J2EE standard. Also, some critical bug fixes.
Create BugRat database
If you are using MySQL for your database server, use the included file
'sql/schema/mysql.sql' to define the database tables. There is also a
schema file for Oracle. If you use another database, start with one of
the existing schemas and modify it to meet your database's requirements.
If you send me your schema file, I will include it in future releases.
Load BugRat configuration
The easiest thing to do is to edit the default configuration
included in 'sql/defconfig.sql' to be what you want, and then
load them by executing the SQL statements in a tool provided
by your database (mysql for MySQL users). I have also included
the configuration for the Giant Java Tree (www.gjt.org) in
'sql/gjtconfig.sql' as an example.
Load BugRat properties
The easiest thing to do is to edit the default properties
included in 'sql/defproperties.sql' to be what you want, and then
load them by executing the SQL statements in a tool provided
by your database (mysql for MySQL users). I have also included
the properties for the Giant Java Tree (www.gjt.org) in
'sql/gjtproperties.sql' as an example.
Load your project and category definitions into database
Use the included example sql to help define your projects and categories.
The example is in 'sql/examplecats.sql'. The categories used for the GJT
BugRat database are in 'sql/gjtcats.sql'. Remember, you can always add
new projects and categories at any time.
Install the servlet.
The advanatage of updating to the modern 2.2 servlet API is that
it specifies a standard for packaging web applications into WAR
files. This greatly simplifies the task of installation. For most
cases, simply installing the bugrat.war file according to your
servlet engine will accomplish the job.
Configure the servlet properties for each servlet.
Once you have deployed the bugrat.war file, you will need to edit
the file WEB-INF/web.xml. This files defines the servlets and their
initialization parameters. The important parameters that MUST be
configured relate to your JDBC connection to your database server.
Note that you may have to start your app server, or servlet engine,
in order to get the WAR file extracted, then stop to edit the web.xml
file, and finally restart the server, in order to complete this step.
Of course, you can always open the WAR, extract the file manaually,
edit, and replace, if you wish.
You MUST set the 'jdbcUrl' and 'jcdbcDriverClassName' parameters
to those required by your JDBC driver to connect to your database
server. The MySQL JDBC driver is included by default. Thus, for
MySQL users, you will not need to change the jdbcDriverClassName
parameter, and your driver is included in the war file.
For those using another database other than MySQL, you will need
to change jdbcDriverClassName, as well as include your JDBC driver's
JAR file in WEB-INF/lib, or somewhere on your servlet engine's
classpath such that the servlet classes can load the driver's
classes.
You may also want to make other adjustments to this file, but no
other changes should be necessary.
MYSQL USERS NOTE: If you have MySQL running on the local host, and
you define a user named 'bugrat' with a password 'password', then
there is a reasonable chance that the BugRat servlets will startup
with no modifications to the web.xml file. Cross your fingers...
Try to run the BugRatViewer servlet to see if you can get
the main menu:
BugRat consists of a number of distinct "pieces" that you must drop into
place in order for BugRat to function properly as a whole. These pieces
are:
An SQL database, currently assumed to be MySQL, but hopefully
configurable to other databases.
WAR containing three Servlets, View, Report, and Admin, and
the html documents that describe BugRat.
EMail filter, a Java application that filters and processes
incoming email reports. This is not required if you do not
intend to process bug reports via email.
DATABASE
BugRat requires an SQL database, accessible via JDBC, to function, as
that is where it stores all of the data. The distribution comes essentially
configured to use MySQL, an excellent database, utilizing the MM.mysql
driver available via . The driver's JAR is
included with the distribution.
BugRat uses a single database, typically named 'bugrat'. You may name
the database any name, as long as you configure the servlet property
'jdbcUrl' to point to the database name that you use.
The database contains 23 tables (25 if you count the auth databases).
The file 'sql/schema/'mysql.sql' contains the MySQL schema for
the BugRat database. There is also a schema file for Oracle. If you
are using a database other than these, you will need to adjust that SQL
to fit your database product.
The two tables, 'adminusers' and 'admingroups', are used for apache
MySQL authorization, if you choose to use that method for authentication
when the BugRatAdmin servlet is accessed. Otherwise, you need not concern
yourself with these tables. Or, you could use them for your own auth
mechanism if possible.
SCHEMA
The distribution includes a schema for MySQL and Oracle. These schema are
located in 'sql/schema/' directory. If you are using a different database
server, modify this file to match your server's SQL syntax. If you send
the new sql to me at
CONFIGURATION
BugRat provides you with a serious amount of configurability. In fact,
vitrually every field in BugRat is configurable. You can give unique
values and names to severity levels, define multiple levels of confidence,
and so on.
Typically, however, most installations only configure the projects,
categories, and subcategories, while leaving all of the other fields
configured to the defaults that come with the distribution.
The distribution includes a series of sql files in the 'sql' directory
that will define a reasonable default configuration. The file named
'defconfig.sql' defines default values for the Class, Severity, State,
Priority, and Confidence fields. You can use these as-is, or adjust
them to meet your needs. The file 'gjtconfig.sql' is the configuration
used for the Giant Java Tree.
PROPERTIES
BugRat stores a number of properties in the database that determine how
the servlets operate (for instance, whether certain features are disabled),
as well as the output of the webpages generated by the servlets. In fact,
many of the properties are required in order for the servlets to function
properly.
The file named 'defproperties.sql' defines the properties required for the
servlets to function. These properties are reasonable defaults and are
satisfactory for most installations. Thus, you should simply run the sql
to load up the defaults, then use updates to change the properties you
wish to customize.
CATEGORIES
BugRat manages a hierarchy of reports and bugs based on the idea of
projects with categories broken down into one level of subcategory.
BugRat allows you to complete customize these projects, categories,
and subcategories via the database.
The file named 'gjtcats.sql' defines projects, categories and subcategories
for the Giant Java Tree. It is a good example to begin with. You should
use this file as a starting point and edit it to meet your needs, then
use it to load the database.
The file named 'examplecats.sql' defines an example project.
NOTE that the hierarchy of the categories is implied by the names.
A project will have the value "." for the category and subcategory
fields, while a category will have a value of "." for the subcategory
field. Subcategories use full names in all three fields. Be sure that
you get this correct, or BugRat will not recognize your hierarchy.
You may also create categories in the Admin servlet.
THREE SERVLETS
Why three servlets? I mean, we could have just as easily rolled everything
into one servlet and made everything much simpler. Right?
First, please remember that BugRat was developed for the GJT in 1998, with
jdk1.1.4 and servlet API 1.2 (I think). It was the dark ages. There was no
Java 2, JSP, web.xml (there was no XML). If BugRat were to be designed today,
it would be (is) very different.
As you will note, the classes for the three servlets, and their superclass
BugRatServlet, are quite large in terms of lines of code.
Rolled into one class, the result would be monstrous. The obvious fix is
to move to JSP pages. However, before I perform that level of refactoring,
I wish to consider better alternatives.
More significantly, authentication would have been less versatile had we
used the single servlet model. As it is designed now, you can use no auth,
the same auth for all three, or custom authentication for each servlet. In
other words, you can allow only the developers to use admin, which provides
the ability to link reports to bugs, edit bugs, etc., while allowing anyone
on the net to use report to submit reports, and viewer to view the database.
Or you could limit admin to developers, report to anyone on the web, and
the viewer only to in-house employees and developers. We could not see any
advantage of further subdividing the servlets beyond the three.
However, please note that BugRat 3.0, currently being worked on, will be
a complete refactoring of the servlets to use a single servlet that drives
lightweight command objects, which in turn build XML, which will then be
processed via XSLT to produce the HTML. This major refactoring will make
BugRat a commercial-quality package that is easily reconfigured and whose
presentation can be changed without ever touching the code. Do not expect
this to be released anytime soon, as it requires that I reach unemployment
nirvana, which does not look highly probable these days.
BugRatViewer
The BugRatViewer is the servlet most users will use when viewing, browsing,
searching or otherwise accessing the database in read-only mode. Only if
configured to do so will users be allowed to add comments to reports in
this servlet. The BugRatViewer is installed the same as the other two,
which is described in detail below.
BugRatReport
The BugRatReport is the servlet used to report bugs. That is, bug reports
gets its own servlet. This servlet basically does nothing but accept
incoming bug reports in various and sundry ways.
BugRatAdmin
The BugRatAdmin is the servlet most developers will use. BugRatAdmin has
all of the features of BugRatViewer, as well as the additional administrative
functions, such as editting reports and bugs, adding comments to reports
and bugs, changing configuration properties, etc.
Servlet Properties and Parameters
You must modify the file WEB-INF/web.xml for your installation, once your
app server has unpacked the bugrat.war file. Or you can unpack it and edit
it. Or you may edit the file in the war file directly. However, you do it,
the file must be modified for your setup. Please see the comments in the
web.xml file for details on what to configure and how.
The web.xml file has a long comment at the beginning to assist you in
editting the file. Please read them!
EMAIL FILTER
BugRat includes a Java application that can act as an email parser to
support the submission of bug reports via email. If you wish to use this
filter, you must compile the application and install it as the filter
for whatever email alias you use for bug report submission. You will
need to configure a few properties in the database so that the email
application knows things like the email address it is based on.
This class is designed as an email filter, so it simply needs the email
to be available via stdin. This is typical for programs like procmail,
which redirect incoming email to various filters. You may also funnel
email into the class with an entry like the following in your /etc/aliases
file (if you are working under UNIX that is):
The following lists the properties that you need to configure in the database.
The first two global properties are used by the servlets as well. The second
two are specific to the email filter.
global.defaultReportState - The default report state
global.defaultReportConfidence - The default report confidence setting
bratm.adminAddress - The email address of the BugRat admin.
bratm.robotAddress - The email address of the filter itself.
Used in help page to tell users where
to email bug reports.
BUGRAT CLIENT
DEPRECATED
The client was an application that is designed to be a full fledged client
for the BugRat database. However, we soon discovered the power of servlets
combined with HTML, and let the client mothball. It still had potential as
an administrative tool, as it provides a slightly better interface for those
type of functions. However, it was more work and maintenance. So we mothballed
it.
DBI
BugRat uses a pachage org.gjt.bugrat.dbi to abstract away the access
to persistent storage. The DBI package is access by the objects that
are defined in org.gjt.bugrat.db. Currently, there is a JDBC layer,
as well as one that allows for tunneling through HTTP for clients.
However, the latter has never been fully implemented and is deprecated.
In the future, I may provide a DBI package that implements the BugRat
persistent storage on top of EJB. Don't hold you breath...
Anyway, you need to be aware of the DBI layer if you wish to work with
the code, but otherwise can ignore the fact that it exists.
PROPERTIES
NOTE - YOU MUST LOAD THE PROPERTIES INTO THE DATABASE.
These are set in the database in table 'properties'. These are all defined
in the file 'sql/defproperties.sql'. YOU MUST LOAD THESE into the database.
The proper way to do this is to edit the file to your needs, and then use a
tool to execute the sql to load it into the database. A few of these are
listed here, but the defproperties.sql file is always the best place to
look. The file is loaded with comments. You may wish to simply load the
defaults into the database without editting defproperties.sql. Then you
can use the admin servlet to edit the properties via a web page.
global.defaultResponsible
The default id used to set the "responsible" field for new reports.
global.defaultResponsible.projectname
The default id used to set the "responsible" field for new reports
for a specific project.
The default confidence level assigned to new bug reports.
There are many more. The best documentation for these properties is in
the 'defproperties.sql' file itself. PLEASE read through these comments
if you have questions about the properties. If the comments do not help
you, then please email the mailing list.
The properties can also be listed by going to the admin servlet and
clicking on the link to list them. However, this list depends on your
having inserted the properties into the database via the defproperties.sql
file, or its equivalent.