Copyright (C)2003 Philipp Bartsch.
This document 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.
Die aktuellste Variante dieses Dokuments und DocWhatsUp sind auf docwhatsup.sourceforge.net zu finden.
Da kein Programm perfekt ist und Fehler, Bugs genannt, Teil jedes Entwicklungsprozesses sind,
stellt sich zwangsläufig die Frage, wie man als Entwickler mit Softwaremängeln umgeht.
Viel zu viele beschränken sich bei der Fehlerbehandlung darauf, einen Stacktrace
in einer Log-Datei verschwinden zu lassen und dem Nutzer kryptisch mitzuteilen, das ein Fehler aufgetreten ist.
Dadurch geht die Erfahrungen des Kunden mit Mängeln am Produkt, eine wertvolle Informationsquelle,
verloren und kann nicht in die Weiterentwicklung des Produkts einfließen.
DWU ermöglicht es, das Auftreten eines Fehlers automatisch zu dokumentieren und ohne Zusatzprogramme per Mail zu
melden. Es ist darauf ausgelegt, das technisch unbedarfte und "ungeduldige" Nutzer nicht verschreckt werden.
DWU arbeitet als eigenständige Bibliothek und muss in kritischen Programmabschnitten explizit aufgerufen
werden, wobei sich der Umfang des Schnittstelle auf 1 bis 2 Methodenaufrufen beschränkt.
DWU erstellt ein Profil des auftretenden Fehlers, indem es einerseits Informationen zum Fehler und Rechner sammelt und speichert es in einer lokalen Profilqueue ab. Anschliessend kann mit dem Profil auf verschiedene Weise gearbeitet werden:
Soll ein Profil nun übertragen werden, werden die Profildaten in ein angegebenes Format exportiert und anhand der vorhandenen Mailingkonfiguration übermittelt. Ist es übertragen worden, wird es lokal gelöscht und seine Signatur vermerkt.
DWU liegt als fertiges JAR Paket vor und muss lediglich im Classpath platziert oder der Classpath um den Pfad von DWU erweitert werden. Die einzige Klasse, mit welcher man später in Kontakt kommt, ist org.shaker.dwu.DocWhatsUp.
Kern eines Fehlerfalls ist ein Fehlerprofil (BugProfile), das dienliche Informationen zum Fehler und zum Zustand des Rechner aufnimmt.
Grundsätzlich enthält ein Fehlerprofil das Exceptionobjekt des Fehlers (oder eine String Fehlerbeschreibung) und die
Fehlerkategorie.
Da das Fehlerprofilobjekt, von Properties abgeleitet ist, können per put(keystring, valuestring)
zusätzliche Informationen, die für den Fehlerkontext relevant sind, übergeben werden; besonderen Mailformaten
wie Bugzilla müssen weitere Informationen übergeben werden, damit sie gültig sind. Die Standardaspekte eines Fehlerfalls
werden weiter unten näher erläutert.
Die Dokumentation der Rechnerinformationen wird durch die Datei filter.properties, die sich im Wurzelverzeichnis
von dwu.jar befindet, bestimmt. Die Datei besteht aus einer durch Zeilenumbrüche separierten Auflistung
von System Property Keys (beispielsweise user.dir\n java.runtime.version\n usw.): der Inhalt jedes gelisteten Properties wird zum Fehlerzeitpunkt
ausgelesen und dokumentiert.
Es ist zu beachten, das filter.properties nur manuell bearbeitet werden kann. Sie sollten vor der Auslieferung
auch nur die interessantesten Properties bestimmen, um den Umfang der Fehlermail gering zu halten, denn die von ihr
bestimmten Properties werden bei JEDEM Fehler dokumentiert.
Wird keine Filterdatei gefunden, werden die Version der Java Runtime, der Name des Betriebssystems und das Fehlen der
Filterdatei als weiterer Fehleraspekt im Fehlerprofil vermerkt.
BugProfile bugProfile = DocWhatsUp.createBugProfile(exception, //exception
"XML Importfehler"[, //Fehlerkategorie
"bugs@projektseite.org"]); //Zieladresse
Prinzipiell besteht ein Fehlerprofil aus den Informationen, die Sie ihm übergeben (Bsp: im Rahmen einer Zählschleife ist vielleicht der Umfang von i oder dem Iterator interessant). Einige Standardinformationen sind jedoch schon vordefiniert, weil sie sich einerseits als generell interessant herausgestellt haben und andererseits für bestimmte Mailformate unabdingbar sind.
| Schlüssel: BugProfile.<> | Erklärung | Auswirkung Bugzilla Format | Auswirkung auf HTML&Text Format |
| ERROR_CLASS | Der Fehlercode-String ist für die Erstellung der Fehlerprofilmail erforderlich. Er spezifiziert, aus welcher Kategorie der Fehler kommt und wird von jedem Ausgabeformat vorausgesetzt. | Benötigt Die Fehlerklasse wird als "component" vermerkt und muss einen Wert enthalten, der Bugzilla bekannt ist, da die Submission sonst verweigert wird. |
Benötigt Wird Teil der Betreffzeile und hilft so, eindeutige Betreffs zur Mailfilterung zu schaffen. Der Aufbau der
Betreffzeile ist wie folgt: DWU caught an error in: "$ERROR_CLASS": $MESSAGE |
| PRODUCT_NAME | Die Produktbezeichnung. Sie wird mittels System.getProperty("product.name") ausgelesen. | Benötigt Der Produktname wird als "product" vermerkt und muss einen bekannten Wert enthalten, da die Submission sonst verweigert wird. | Teil der Fehlerbeschreibung im Mailbody. |
| PRODUCT_VERSION | Die Produktversion. Sie wird mittels System.getProperty("product.version") ausgelesen. | Benötigt Der Produktname wird als "version" vermerkt und muss einen bekannten Wert enthalten. | Teil der Fehlerbeschreibung im Mailbody. |
| USER_COMMENT | Der Nutzerkommentar, also der Inhalt des Kommentarfeldes im Fehlerdialog (wird automatisch ausgelesen). | Der Kommentar des Nutzer wird Teil der Fehlerbeschreibung und wird nicht vorausgesetzt. | Teil der Fehlerbeschreibung im Mailbody. |
| MESSAGE | Eine kurze Fehlerbeschreibung. | Wird als "short_desc" verwendet. | Wird in der Betreffzeile und in der Fehlerbeschreibung im Mailbody hinterlegt. |
| MAIL_TO |
Die Mailadresse des Empfängers. Wird Sie nicht direkt durch setProperty(BugProfile.MAIL_TO,...)
übergeben, wird sie aus settings.dwu ausgelesen, in welchem ein Standardempfänger
(neben weiteren) angegeben werden kann. Siehe auch: 3.5 DWU Konfiguration |
Hier muss der entsprechende bugzilla account übergeben werden, über den mail submissions vorgenommen werden können. | -. |
| FORMAT |
Das zu verwendende Format für das Fehlerprofil. Mit Hilfe dieses Properties ist es möglich, Fehlerprofilen
unterschiedliche Formate zuzuweisen, nach welchen sie zu verschicken sind. Wird kein Format bestimmt, wird das
in settings.dwu beschriebene Standardformat verwendet. Gültige Angaben sind: html, bugzilla und text. Siehe auch: 3.5 DWU Konfiguration |
Stellt sich heraus, das Bugzilla als Format gewählt wurde, jedoch nicht genügend Informationen für eine valide
Meldung zur Verfügung stehen, wird auf das in settings.dwu beschriebene
Ausweichformat zurückgegriffen (oder text, wenn nicht möglich)
Siehe auch: 3.5 DWU Konfiguration |
- |
Was kann man nun mit dem erstellten Fehlerprofil machen? Zunächst einmal: es ist lokal in der Queue gespeichert und verbleibt dort, bis es verschickt wird. Handelt es sich um einen weniger schwerwiegenden Fehler, der dem Nutzer nicht mitgeteilt werden muss, kann man ihn nach der Erstellung ignorieren und fortfahren, er würde später zusammen mit den anderen Fehlerprofilen versendet werden. Möchte man den Fehler gleich versenden lassen oder dem Nutzer mitteilen, bieten sich verschiedene Varianten an:
Der Fehlerdialog enthält 3 Tabs:
DocWhatsUp.showErrDialog(bugProfile, // das Fehlerprofil
parentalFrame,
errorMessageForTheUser[, // eine Fehlernachricht für den Nutzer
hintMessageForTheUser]); // ein optionaler Hinweis/Workaround o.ä.
Der Infodialog beschränkt sich auf den Informationstab des Fehlerdialogs (siehe oben). Er
erscheint übrigens auch an Stelle des Fehlerdialogs, wenn ein Fehler aufgetreten ist, der bereits
gemeldet wurde, um redundanten Versand von Fehlerberichten zu vermeiden.
Aufruf:
DocWhatsUp.showMsgDialog(parentalFrame,
errorMessageForTheUser[, // eine Fehlernachricht für den Nutzer
hintMessageForTheUser]); // ein optionaler Hinweis/Workaround o.ä.
Der Aufruf dieser Methode erstellt aus allen in der Queue vorhandenen Profilen Mails und versucht,
diese auf Basis der Mail-Konfiguration zu versenden. Damit diese Methode
erfolgreich abschliesst, muss eine Verbindung zum Mailserver bestehen.
Aufruf:
DocWhatsUp.submitBugQueue();.
Im Gegensatz zu den Fehler- und Infodialogen kann man das BlackBoard auch ausserhalb eines
Fehlerkontexts, also ohne das Vorhandensein eines gerade aufgetretenen Fehlers, aufrufen. Das schwarze
Brett kann beispielsweise als Panel im Über-Dialog-Bereich eines Programms platziert, oder aber
als JDialog dargestellt werden.
Das BlackBoard stellt die aktuelle Mailkonfiguration und eine Fehlerstatistik dar, also wieviele
Fehlerprofile inzwischen aufgetreten und wieviele bereits versendet wurden. Ausserdem kann in dieser
Stelle der stille Versand gestartet werden.
Aufruf als Panel:
JPanel panel = DocWhatsUp.getBlackBoard(Window);
DocWhatsUp.getBBDialog(Window).show();
Die Mailkonfiguration beschreibt die für den Fehlerberichtversand zu verwendenen Server.
Es gibt folgende Einstellungen:
| Property | Beschreibung | Format |
| mail.from | Die Absenderadresse | username@hostname.tld |
| mail.host | Der SMTP Server | Standard URL (RFC 1738) |
| mail.host.port | Der Port des SMTP Servers | Zahl zwischen 1 und 65536 (Standard ist 25) |
| mail.pop | Der zur POP Authentifizierung verwendete POP Server | Standard URL (RFC 1738) |
| mail.pop.port | Der Port des POP Servers | Zahl zwischen 1 und 65536 (Standard ist 110) |
| mail.user | Der Name des verwendeten Mailkontos | String |
| mail.pass | Das Passwort des Mailkontos | String |
#This properties file provides a default mail account setting. #NO FITNESS WARRANTY! Custom settings are preferred. #Please 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_passwdGespeichert werden die Einstellungen in den zwei unterschiedlichen Dateien, die unterschiedliche Zwecke erfüllen: zum einen gibt es die Datei default.mta ("mta" wie Mail Transfer Agent), die sich im Wurzelverzeichnis der Datei dwu.jar befindet und zum anderen die Datei ~/.docwhatsup/custom.mta.
Neben den Angaben des zu verwendenden Mail Servers kann man mit Hilfe der Datei settings.dwu das
Verhalten von DWU genauer steuern und sich durch geschickte Angaben in dieser Datei einige Schreibarbeit beim Aufruf der DWU Schnittstelle
ersparen.
Neben den Signaturen der versendeten Fehlerreports dient diese Datei dazu, Standardwerte und Verhaltensweisen festzulegen. DWU besitzt
keine Mechanismen, diese Werte selbständig zu manipulieren; sie sollten also, wie bei der oben erwähnten Datei
filter.properties, vor der Auslieferung sinnvolle Werte setzen.
| Schlüssel | Erklärung |
| mailing | Ist dieser Wert nicht auf "true" gesetzt, ist es nicht möglich, Mails per DWU zu versenden. Der Fehlerdialog wird keine Meldelasche enthalten und der Aufruf von DocWhatsUp.submitBugQueue() bleibt folgenlos. |
| dialogs | Ist dieser Wert nicht auf "true" gesetzt, werden keine DWU Dialoge dargestellt. |
| cc | Diesem Wert kann eine kommaseparierte Liste von Mailadressen übergeben werden, wobei JEDE Adresse JEDEM Fehlerbericht als zusätzlicher Empfänger mitgeteilt wird. |
| alt | Dieser Eintrag bestimmt einen Ausweichempfänger für den Fall, das ein angefordertes Format nicht erstellt werden konnte, oder kein Empfänger spezifiziert wurde. |
| format | Dieser Eintrag bestimmt das Standardformat der Mail. Mögliche Werte sind html, bugzilla und text. Sollten Sie hier ein kritisches Format eintragen, das einen bestimmten Informationsumfang benögt, der zum Fehlerzeitpunkt nicht befriedigt werden kann (wie Bugzilla), wird text verwendet! Ausserdem wird für den Fall, das ein Format nicht "gesättigt" ist, auf die unter alt angebene Empfängeradresse ausgewichen! |
| maintain |
Dieser Eintrag enthält die Adresse des DWU Maintainers. Ist dieser Wert vorhanden und mit einer validen Adresse versehen,
verschickt DWU im Schatten von Fehlerberichten eigene Statusmeldungen, die anonymisierte Logmessages enthalten. Sollten Sie nicht wünschen, das DWU eigene Berichte verschickt, entfernen Sie den Eintrag. Selbstverständlich können Sie (hoffentlich neben meiner Adresse ;)) auch eine eigene Adresse einfügen, wenn Sie sich an der Weiterentwicklung von DWU beteiligen möchten. |
Der Fehlerbericht ist eine Visualisierung des Fehlerprofils, enthält also einerseits die konkreten Fehlerdaten
als auch die System Properties, die mittels filter.properties spezifiziert wurden. Wie dies
im einzelnen aussieht, können Sie in Beispielen auf docwhatsup.sourceforge.net
betrachten. Alternativ kann auch mittels "shell$java -jar dwu.jar" eine Test session gestartet
werden, die in Abhängigkeit von Ihren Angaben einen Testreport erstellt.
Sie arbeiten an einem Projekt und haben sich entschlossen, DWU als Feedback Agent zu installieren. Um DWU zu integrieren, bieten sich folgende Schritte an:
DWU ist steht unter der GPL. Kann ich es trotzdem in meinem kommerziellen Programm nutzen ?
Es is möglich, DWU in Verbindung kommerziellen Produkten zu nutzen, ein entsprechender Zusatzparagraph ist Teil der Lizenz, wobei
Veränderungen an DWU nachwievor der GPL unterliegen und damit offen sein müssen. Dieses ist allerdings auf die Nutzung
der DocWhatsUp.java Schnittstelle beschränkt.
Es wäre nett, wenn Sie im Gegenzug zur Nutzung von DWU Ihre Erfahrungen einbringen würden :).
Warum wird nicht XML zur Speicherung der Einstellungen und Fehlerprofile genutzt?
So läuft DWU auch mit älteren JREs (getestet wurde es ab 1.2.2). XML Processing gehört erst seit 1.4 zum Umfang der JRE.
Die würde bedeuten, dass das entsprechende Parser Framework entweder mit DWU oder mit dem überwachten Produkt ausgeliefert werden
müsste, was den Umfang selbiger erheblich steigern würde.
Ich überlege allerdings, eine weitere Version anzubieten, die XML nutzt: wenn jemand daran interessiert ist, bitte melden!