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.
The latest version of this document and DocWhatsUp are at docwhatsup.sourceforge.net You may want to check for changes.
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).
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
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.
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.
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 "firstname.lastname@example.org"]); //Recipient
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.
|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.|
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.||-|
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 contains 3 Tabs:
DocWhatsUp.showErrDialog(bugProfile, // the BugProfile parentalFrame, errorMessageForTheUser[, // a description hintMessageForTheUser]); // a hint/workaround (optional)
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.
DocWhatsUp.showMsgDialog(parentalFrame, errorMessageForTheUser[, // a description hintMessageForTheUser]); // a hint/workaround (optional)
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.
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);
The mail configuration specifies the used mail server.
|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|
#This properties file provides a default mail account setting. #NO FITNESS WARRANTY! Custom settings are preferred. #Be fair and don`t misuse this account. email@example.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_passwordThese 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.
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.
|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 :)|
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.
You created a program and want to integrate DWU as a feedback agent? The following steps should be proceeded:
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!