Doc What`s Up Manual

Philipp Bartsch (DocWhatsUp[AT]gmx.net)

v0.82, 2003.07.23

This document describes the installation and configuration of Doc What`s Up (DWU), the Java Bugprofiling and -reporting tool.


1. Introduction

2. What`s Up?

3. Usage

4. How to integrate DWU

FAQ

GNU GPL License




1. Introduction

Copyright (C)2003 Philipp Bartsch.
This document and the "DocWhatsUp" tool is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Please note, that closed source programs can freely use DocWhatsUp using the DocWhatsUp-class interface, a proper license statement is part of the source files.

The latest version of this document and DocWhatsUp are at docwhatsup.sourceforge.net You may want to check for changes.




2. What`s Up?

One way to help ensure the code is full of bugs is to
ensure the maintenance programmers never hear about them

From: How to write unmaintainable code

No program is perfect and creating bugs is part of every development progress. Unfortunately, most of the programmers face this problem by writing log files only or showing cryptic error dialogs, that don`t help. Even if you ask the user for a mail report, the resulting notification mostly doesn`t fit the programmers needs: all you get is a "your program doesn`t work, ill use something else, stupid!".
DWU enables you (or better: the unexperienced user) to log and send every occuring bug easily and automatically without external programs.
DWU is a independend java library that uses JavaMail and the Java Activation Framework and gets called (3-5 lines) in critical parts of the program (like catch statements).


2.1 Features


2.2 How it works

A DWU "session" starts with the creation of a BugProfile. It contains some basic informations like a stacktrace and an error code, but can easily be extended with further infos (like the current state of the iterator that crashed or ...). Furthermore it collects defined System Properties (like the os.name or whatever) and gets saved finally in a BugProfile queue where it resides until the user sends it.
What can you do with the profile? DWU offers 3 types of dialoges: an Errordialog that has a "what happend" and "submit the error"-tab and a simplified Messagedialog without the submission tab. Another type of dialog/panel is the BlackBoard: it works without an errorcontext, you can call and embed it whereever you want. It offers some statistics about the current mailing configuration, occured and submitted profiles and the possibility to reconfigure the mail settings and to send all profiles. There`s also a submission method that creates no dialog but sends all BugProfiles to the specified recipient quietly. If the user decides to send the BugProfiles, the profiles get exported into the specified format and deleted from the queue when the submission is performed.


2.3. Installation

DWU is a ready to use jar package and a lib subfolder that contains the appropriate libraries. Add the dwu.jar path to your classpath and have a look at org.shaker.dwu.DocWhatsUp, which provides all necessary methods. That`s it.




3. Usage


3.1 The BugProfile

The core of each DWU session is the BugProfile, which collects details about the occured error and the current machine state; it needs at least the exception object (or a descriptive error description string) and the error class (category of error).
The BugProfile is a extended java.util.Properties object, so you can easily add further details via put(keystring, valuestring), formats like Bugzilla even need further informations to be valid (description follows)

The documentation of the machine state is controlled by the filter.properties file, that is located in the root path of dwu.jar. This positive filter file consists of a linebreak separated list of system properties (like user.dir\n java.runtime.version\n etc.): the content of each listed property gets read and saved if an error occures. Please note, that this file can only be changed manually, so you have to determine all interesting properties before you ship your project and keep the list as small as possible to lower the size of a BugMail, because all properties get documented for every occuring bug (except the reported ones, they will be ignored).

An example:
BugProfile bugProfile = DocWhatsUp.createBugProfile(exception,                 //exception object or description string
                                                    "XML import error"[,       //Error class
                                                    "bugs@projectpage.org"]);  //Recipient

3.2 What does a BugProfile contain

Basicly, the BugProfile contains all you put into it (if your iteration fails, you are probably interested in the state of your i or the iterator object -- use put(...) and it gets documented). Some standard informations are predefined, because they are generally interesting or necessary for some mail formats.

The standard keys and their effect on the mail formats

Key: BugProfile.<> Description Bugzilla Format HTML&Text Format
ERROR_CLASS The error class string is required for every format. It specifies the category of the error. Required The error class gets registered as "component" and has to contain a valid value or the automatic submission will fail. Required Is part of the subject line and supports mail filtering that way. What does a subject line look like: DWU caught an error in: "ERROR_CLASS": MESSAGE
PRODUCT_NAME The product name. Gets read by System.getProperty("product.name") RequiredThe product name get registered as "product" and has to contain a valid value or the automatic submission will fail. Part of the mail body.
PRODUCT_VERSION The product version. Gets read by System.getProperty("product.version") RequiredThe product name get registered as "version" and has to contain a valid value or the automatic submission will fail. Part of the mail body.
USER_COMMENT The user comment (the content of the comment text area); gets read automaticly. The comment is part of the bug description and not necessary. Part of the mail body.
MESSAGE A short error description Gets included as "short_desc". Is part of subject line and mail body.
MAIL_TO The recipient address. If you don`t specify it by setProperty(BugProfile.MAIL_TO,...) DWU reads it from settings.dwu which specifies a default recipient. (3.5 DWU Configuration). The user comment is part of the bug description and not necessary. Part of the mail body.
FORMAT The intended mail format. If nothing is specified, DWU reads it from settings.dwu which specifies a default recipient.
(3.5 DWU Configuration). Valid values are text, bugzilla and html.
If you specify bugzilla or another sensitive format without providing enough details, DWU uses the default format specified by settings.dwu (3.5 DWU Configuration). If the default format can`t be used too, it falls back to text. -


3.2 Work with the profile

What can you do with a BugProfile? First of all: it has been saved in a local queue and resides there until the user sends it.
If the occured error is a minor one and not worth to be displayed, you can ignore the BugProfile object and carry on: if the user decides to send another BugProfile, the "minor" one gets send too quietly. If you want to display and/or submit the error, DWU provides different possibilities:



The Error Dialog

The Error Dialog contains 3 Tabs:


Example:
DocWhatsUp.showErrDialog(bugProfile,               // the BugProfile
                         parentalFrame,			 
                         errorMessageForTheUser[,  // a description
                         hintMessageForTheUser]);  // a hint/workaround (optional)


The Message Dialog

The Message Dialog just displays the Information-tab of the Error dialog. It gets displayed instead of the Error Dialog if a given Bug has already been submitted.

Example:

DocWhatsUp.showMsgDialog(parentalFrame,			 
                         errorMessageForTheUser[,  // a description
                         hintMessageForTheUser]);  // a hint/workaround (optional)


The immediate and quiet submission

This method collects all queued BugProfiles, exports them into mails and tries to send them using the specified mail configuration. This method requires a established connection to the smtp server.

Method:

DocWhatsUp.submitBugQueue();.


BlackBoard Panel

In contrast to the Message and Error Dialogs, this panel doesn`t need a error context. It can be embedded into a given panel (like the about dialog or elsewhere) and called as a JDialog.
The BlackBoard displays the current mail configuration and a Profile statistic, summarising the number of queued and submitted Profiles. Furthermore, the user can (re-)configure the mail settings here and send all queued BugProfiles with a single button (calling submitBugQueue() in the background).

Creating a BB Panel:

JPanel panel = DocWhatsUp.getBlackBoard(Window);

Creating a BB Dialog:
DocWhatsUp.getBBDialog(Window).show();


3.3 Mail Configuration

The mail configuration specifies the used mail server.

Property Description Format
mail.from Die Absenderadresse username@hostname.tld
mail.host The SMTP Server Standard URL (RFC 1738)
mail.host.port SMTP Server port An integer between 1 and 65536 (25 is default)
mail.pop The POP Server used for POP Authentification Standard URL (RFC 1738)
mail.pop.port POP Server port An integer between 1 and 65536 (110 is default)
mail.user The name of the used mail user account String
mail.pass The password of the user account String

An example:

#This properties file provides a default mail account setting. 
#NO FITNESS WARRANTY! Custom settings are preferred. 
#Be fair and don`t misuse this account.
mail.from=yourname@yourhost.com
mail.pop=pop.yourhost.com
mail.host.port=25
mail.host=smtp.yourhost.com
mail.pop.port=110
mail.user=your_user_name
mail.pass=your_password
These informations get saved in two different files covering different purposes: on the one hand there is default.mta ("mta" means Mail Transfer Agent), located in the root path of dwu.jar and on the other hand ~/.docwhatsup/custom.mta.
The first file contains a standard configuration delivered by the project owner (probably you) and refers a mail account which can be used by DWU, omitting the creation of a custom mail configuration for most of the users.
If the user creates a custom configuration, his settings get stored in ~/.docwhatsup/custom.mta. By the way: the custom settings file doesn`t save the user password, DWU asks for it on every submission process.

3.5 DWU Configuration

Next to the settings delivered by the mail configuration file, settings.dwu controls the basic behaviour of DWU and saves the signatures of the submitted BugProfiles.
This file has to be edited manually and configured properly before you deliver DWU.

Key Description
mailing If this property isn`t set to true, DWU won`t send any mail reports. The Error Dialog won`t contain a Report-tab and DocWhatsUp.submitBugQueue() simply returns.
dialogs If this proeprty isn`t set to true, DWU won`t display any dialogs.
cc This property can contain a comma separated listing of mail addresses, where every address gets registered as a CC recipient for every BugProfile submission.
alt This property specifies an alternative recipient that gets used if no recipient has been specified for a BugProfile or if a format could not be satisfied.
format The value of this property determines the standard mail submission format. Possible values are html, bugzilla and text. If you specify a sensible format like Bugzilla, which can`t be "satisfied" due to a lack of details, DWU uses text! Note that DWU uses the recipient specified by alt if a format can`t be satisfied!
maintain Delivering DWU with this property and a (comma separated) list of DWU maintainer addresses enables DWU to send own maintenance mails containing status messages (own Bug reports). I would be happy if you keep this entry in your DWU configuration :)

3.6 The Bug Report

Depending on the specified format, DWU exports each BugProfile and sends it via Mail. For examples how these formats look like, please have a look at docwhatsup.sourceforge.net.
Alternativly you can start a DWU test session by executing "shell$java -jar dwu.jar". It creates a test report depending on your settings.




4. How to integrate DWU

You created a program and want to integrate DWU as a feedback agent? The following steps should be proceeded:





FAQ

DWU is licensed under the GPL. Can I use it with my closed source program ?

Yes. Normally, the GPL doesn`t permit that, but I extended the license, so you can use DWU together with closed programs, but it`s limited to the usage of the DocWhatsUp class interface. Creating BugProfile/Dialogs another way is not allowed together with closed source software. Modifications and forks of DWU are licensed under GPL too.

Why don`t you use XML to save the profiles and settings?

Sun`s JRE supports XML processing since version 1.4., that way DWU runs also on older JREs (tested with 1.2.2 and above). Adding XML libraries to DWU or your program would bloat it a lot, but if you are interessted in a xml enabled version DWU, send me a mail!