/* UndefinedMacro: TableOfContents(None) */

Vorwort

Mit den jüngsten Umstellungen auf ein einheitliches Build-System gibt es eine Reihe von weiteren Regeln, die beim Coden beachtet werden sollen. Zum einen soll diese Page eine Anleitung für den im Projekt enthaltenen ANT-Build sein, aber auch andere Aspekte wie Code Qualität und Unit-Testing erläutern.

ANT

Was ist ANT?

Ant ist analog zu “make”, dem vielleicht besser bekannten Build-Tool für C, ein Tool, welches alle Verarbeitungsschritte vom Quellcode zum fertig Lauffähigen Programm anhand einer Konfigurationdatei ausführt. Die Konfigurationsdatei für ANT-Builds ist XML-basiert und heisst in der Regel “build.xml”. Ruft man das Programm ANT ohne Parameter in einem Verzeichnis auf, indem eine solche “build.xml” Datei liegt, wird das Default-Target der Konfigurationsdatei ausgeführt. Wer sich weiter über ANT informieren möchte, sollte sich http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/ant/ant.html anschauen.

ANT in Eclipse

Integration

ANT View hinzufügen

Build-Script zum View hinzufügen

Liste von ANT targets

Projekt-spezifische und Benutzerspezifische Property-Datei

Es gibt bestimmte Build-Parameter, die jeder für sich selbst setzen kann, ansonsten werden sinnvolle Defaultwerte verwendet. Diese sind in der Datei build.properties angegeben. Um Default-Werte zu überschreiben legt man sich am besten eine eigene Property-Datei an. Das Buildsystem liest automatisch eine Benutzerspeyifische Property-Datei ein, wenn diese im gleichen Verzeichnis wie die build.properties Datei liegt und “<username>.properties” benannt ist. Dabei muss “<username>” mit dem Namen des aktuellen Systembenutzers ersetzt werden.

Was ist mein System Benutzername?

Beim starten des ANT Builds wird der Benutzername ausgegeben:

Buildfile: build.xml

init:
     [echo] Your username is ddoerr. Try reading ddoerr.properties...

Anpassen des JDK Pfades

Hin und wieder kommt es vor, dass der ANT Build nicht das JDK Verzeichnis findet. Dieses kann man in der “<username>.properties” Datei mit folgendem Eintrag richtig setzen:

jdk.home=/path/to/jdk

Code Qualität

Eclipse

Zur Überprüfung der Code Qualität setzen wir 3 verschiedene Tools ein.

1. Eclipse Code Formatter [builtin]

rosep} Der in Eclipse Integrierte Code Formatter lässt sich bequem über eine XML-Date Konfigurieren, die dem Proejekt under etc/eclipse_codeformatter.xml beigelegt ist. Um die Datei zu importieren gehe man in Projekt → Eigenschaften → Java Code Style → Formatter. Dort aktiviert man die Projektspezifischen Einstellungen und importiert die oben angegebene Datei.

2. Checkstyle

Checkstyle kann einerseits direkt über den ANT-Built gesteuert werden (Target: checkstyle), aber eine direkte Integration in Eclipse ist natürlich viel bequemer. Glücklicherweise gibt es ein Checkstyle Plugin, was allerdings erst installiert werden muss. Unter Hilfe → Neue Software Installieren kann man das tun, die Update-Site für Checkstyle ist http://eclipse-cs.sf.net/update/. Sobald man das Checkstyle Plugin installiert hat, wird die Konfiguration automatisch aus dem Projekt-Verzeichnis ausgelesen, sodass nichts weiter eingestellt werden muss. Nachdem manuell in Eclipse die Neucompilation der Klassen erzwungen hat, werden die Checkstyle Fehlermeldungen angezeigt.

3. JUnit

Bitte schreibt für jede implementierte Klasse eine JUnittest. Eclipse bietet umfangreiche Unterstützung dafür. Im Projekt verwenden wir die aktuelle JUnit-Version 4.6. Bitte haltet euch an die aktuellen Konventionen, wie ein JUnit-Test auszusehen hat. Unter http://code.google.com/p/t2framework/wiki/JUnitQuickTutorial kann man sich hierzu weiter informieren.

Log Meldungen mit log4j

Logmeldungen werden nicht nur geduldet, sondern sind ausdrücklich erwünscht. Sie sollten aber keinesfalls über System.out.println() ausgegeben werden, sondern über einen Logger.

Jede Klasse solllte seine eigene Logging Instannz besitzen. Dies ermöglicht nachher die grösstmögliche Flexibilität im An-/und Ausschalten von Logmeldungen. Hier ist eine Beispielklasse, die zeigt, wie man einen Logger erstellt und benutzt:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

public class LogExample {

    // mit diesen und keinen anderen Modifiern erstellt man eine Log Instanz!
    private static final Log LOG = LogFactory.getLog(LogExample.class);
    
    
    public void foo(){
        LOG.debug("Das ist eine Debugmeldung");
        LOG.info("Das ist eine Infomeldung");
        LOG.error("Das ist eine Fehlermeldung");
    }
}

Die Konfiguration der Ausgabe und des Log Levels erfolgt über die Property-Datei “log4j.properties”, die wie alle Property-Dateien im Classpath enthalten sein muss. In dieser Datei kann das Loglevel und die Art der Ausgabe (Console, Datei, Email, etc…) im Allgemeinen, aber auch für Packages und Klassen detailiert konfiguriert werden. Zur Zeit gibt es 3 Arten der Ausgabe: Error-Meldungen werden auf der Konsole ausgegeben, dann gibt es zwei Log-Dateien, error.log fuer Fehlermeldungen und debug.log mit allen Meldungen des gesamten Programms. Mehr Informationen zu log4j im Allgemeinen gibt es unter http://logging.apache.org/log4j/1.2/manual.html und hier ein Dokumentiertes Beispiel einer log4j.properties Datei: http://www.java2s.com/Code/Java/Language-Basics/Examplelog4jConfigurationFile.htm

log4j.rootLogger=DEBUG, CONSOLE, ERROR_LOGFILE, DEBUG_LOGFILE
log4j.logger.org.eclipse=ERROR, CONSOLE, ERROR_LOGFILE, DEBUG_LOGFILE

# CONSOLE is set to be a ConsoleAppender.
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.threshold=ERROR
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%-5p %c %x - %m%n

# DEBUG_LOGFILE is set to be a FileAppender
log4j.appender.DEBUG_LOGFILE=org.apache.log4j.FileAppender
log4j.appender.DEBUG_LOGFILE.threshold=DEBUG
log4j.appender.DEBUG_LOGFILE.File=debug.log
log4j.appender.DEBUG_LOGFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.DEBUG_LOGFILE.layout.ConversionPattern=%-5p %d [%t] %c %x - %m%n

# ERROR_LOGFILE is set to be a RollingFileAppender
log4j.appender.ERROR_LOGFILE=org.apache.log4j.RollingFileAppender
log4j.appender.ERROR_LOGFILE.threshold=ERROR
log4j.appender.ERROR_LOGFILE.File=error.log
log4j.appender.ERROR_LOGFILE.layout=org.apache.log4j.PatternLayout
log4j.appender.ERROR_LOGFILE.layout.ConversionPattern=%-5p %d [%t] %c %x - %m%n

Neuen Sourcecode in Versionskontrollsystem committen

Bevor man einen Commit in das RoseV2 SVN macht, sollte man das ANT “build” target ausführen. Dieses stellt sicher, dass der einzucheckende Code auch bei den anderen Projektteilnehmern läuft, abe auch dass die Code Qualität gewährt ist.

Schlägt der Build fehl, darf nicht eingecheckt werden, bis alle Probleme beseitigt sind.