Inhalt

Installation JBoss/Eclipse
Eclipse und WebTools-Plugin konfigurieren:
Java Development Kit
JBoss 4.0.3
XDoclet einrichten
WebTools-Plugin goes Internet
Eclipse-Codeformatter
Projektstruktur
Debugging
JBoss-Knowhow:
Generierte JSP-Java-Klassen
JMXConsole und JNDIView
Logging
Bugs und Troubleshooting


Installation JBoss/Eclipse

ACHTUNG: XDoclet wollte in einem Fall nicht starten, vermutlich weil Eclipse und XDoclet in einem Pfad installiert waren der Leerzeichen enthielt. Also keine Verzeichnisse á la "d:\Meine Dateien\Eclipse" verwenden, egal für welche Komponente.

Eclipse und WebTools-Plugin konfigurieren

Java Development Kit

Zuerst einmal müssen wir Eclipse mitteilen dass es ein JDK statt der im Default referenzierten Runtime verwenden soll (da JSPs bis Tomcat 5.0 auf jeden Fall und danach eventuell ein JDK erfordern). Also in "Window" -> "Preferences..." gehen und links in der Übersicht den Punkt "Java" -> "Installed Runtimes" wählen. Wir sehen die auf dem Rechner gefundene Runtime.
JDK konfigurieren, Schritt 1
Also eine neue per "Add..." zufügen. Wir wählen das Verzeichnis des JDK und vergeben einen Namen.
JDK konfigurieren, Schritt 2
Jetzt noch den Haken beim JDK setzen (der Haken bei der Runtime verschwindet automatisch) und wir sind fertig.

JBoss 4.0.3

In "Window" -> "Preferences..." gehen und links in der Übersicht den Punkt "Server" -> "Installed Runtimes" wählen. Über "Add..." einen neuen Server zufügen. Wir wählen einen Server vom Typ "JBoss 4.0.x" aus.
JBoss konfigurieren, Schritt 1
Im nächsten Schritt als Runtime das eben angelegte JDK auswählen und als "Application Server directory" und "Classpath variable" jeweils das Wurzel-Verzeichnis des JBoss auswählen. Liegen wir beim Classpath falsch wird uns das durch Fehlermeldungen mitgeteilt.
JBoss konfigurieren, Schritt 2
Zurück im Preferences-Dialog setzen wir noch einen Haken vor dem Server und sind fertig.
JBoss konfigurieren, Schritt 3


XDoclet einrichten

Unter "Window" -> "Preferences" -> "XDoclet" finden wir in die XDoclet-Konfiguration.
Wir aktivieren den "XDoclet Builder", wählen das XDoclet-Home-Verzeichnis aus und wählen die aktuell installierte Version.
XDoclet
Im Unterpunkt "ejbdoclet" setzen wir den Haken vor dem Task "JBoss" (aktiviert die JBoss-spezifischen XDoclet-Erweiterungen).
XDoclet (ejbdoclet)
Den Task "JBoss" wählen und auf "Edit..." klicken. Im erscheinenden Dialog die Version "4.0" wählen.
XDoclet (ejbdoclet für JBoss 4)
Dito für "webdoclet": auch hier den Task "JBoss" aktivieren.
XDoclet (webdoclet)
Die JBoss-Version auf auf "4.0" setzen.
XDoclet (webdoclet für JBoss 4)
Nebenbei: XDoclet wird als separater Ant-Task aufgerufen, die Datei des Ant-Tasks wird vom WTP generiert und im Workspace an dieser Stelle: "\.metadata\.plugins\org.eclipse.jst.j2ee.ejb.annotations.xdoclet\tempAnt.xml".


WebTools-Plugin goes Internet

Jedesmal wenn man eine XML-Datei öffnet oder sie von einem Buildprozess berührt wird versucht der Plugin sie gegen ihre DTD oder ihre Schemadefinition zu validieren. Zur Info: beim Herunterladen einer Datei aus dem Sun-Bereich erscheint jedesmal ein License Agreement, dieses bestätigen.
An der FH müßt ihr den Proxy unter "Window" -> "Preferences" im Punkt "Internet"-> "Proxy Settings" eintragen.
Proxy
Die DTDs und XSDs werden nach dem Laden aus dem Internet und in einem lokalen Cache gespeichert. Den Inhalt des Caches kann man unter "Window" -> "Preferences" im Punkt "Internet" -> "Cache" anschauen, oder im Dateisystem im Workspace-Unterzeichnis ".metadata\.plugins\org.eclipse.wst.internet.cache".
WTP-Cache
ACHTUNG: Falls euer Internetprovider die Angewohnheit hat den ersten Zugriff nach Aufbau der Verbindung auf die eigene Homepage umzuleiten kann es sein dass dies genau die DTD-Definition ist die der WTP-Plugin laden will. Und schon hat er eine HTML-Datei gefressen und meckert über das falsche Format.


Eclipse-Codeformatter

Damit der Quellcode zumindest innerhalb einer Projektgruppe bei allen gleich aussieht empfehle ich die Codeformatierungs-Optionen von Eclipse zu vereinheitlichen. Dies geschieht über "Window" -> "Preferences" -> "Java" -> "Code Style" -> "Formatter", wo man ein neues Profile zufügt. Im folgenden die in meinen Beispielen verwendeten Einstellungen:
Eine Mischung aus Tabs und Leerzeichen sieht in einem anderen Editor meistens müllig aus, deshalb nur Leerzeichen für Einrückung verwenden. Und mit nur 2 Leerzeichen sparen wir Platz.
Indentation
Ich bevorzuge öffnende Klammern auf der gleichen Spalte wie die schließende Klammer, also viele Zeilenumbrüche.
Braces
Passend zu den Zeilenumbrüchen vor öffnenden Klammern mag ich sie auch nach schließenden Klammern.
Control Statements
Die maximale Zeilenlänge bis zu einem vom CodeFormatter erzwungenen Zeilenumbruch würde ich von 80 auf 120 erhöhen.
Line Wrapping
Das Formatieren von Kommentaren habe ich ausgeblendet da die XDoclet-Kommentare für die JBoss-Beispiele dadurch nicht mehr ordentlich aussehen.
Comments


Projektstruktur

Die Struktur eines Projekts (im Beispiel das Stateless-Beispiel mit EJB-Projekt, Webprojekt und ApplicationClient) sieht auf Festplatte so aus:
Projektstruktur
Wird das Projekt auf einen Server geschoben (im Beispiel ein JBoss) muss die EAR-Datei erstellt werden. Dazu werden alle relevanten Daten in das Verzeichnis "%WORKSPACE%\.metadata\.plugins\org.eclipse.core.resources\.projects\Stateless\org.eclipse.jst.server.jboss\Stateless" geschoben.
Projektstruktur beim Publish
Hier landen die JAR-Dateien für die einzelnen Module (StatelessClient.jar, StatelessEJB.jar und StatelessWeb.war) sowie der Deployment-Deskriptor der gesamten Anwendung. Aus diesen Daten wird die EAR-Datei erzeugt und auf den Server verschoben.


Debugging

Zum Debuggen dürfen wir den JBoss nicht "normal" starten sondern im Debug-Modus (Rechtsklick auf den Server, "Debug" wählen).
Debug-Modus
Im folgenden beziehe ich mich auf Klassen aus dem ersten Beispiel, "Stateless".
Wir setzen einen Breakpoint im doPost von GeometricModelServlet. Anschließend im Browser zu dieser URL navigieren:
http://localhost:8080/StatelessWeb/servlet/GeometricModelServlet. Wenn wir alles richtig gemacht haben schiebt sich Eclipse in den Vordergrund, und wir werden gefragt ob wir in die Debug-Perspective wechseln wollen (machen wir natürlich).
Debug-Perspective
Leider sehen wir nur die Fehlermeldung "Source not found", was daran liegt dass der JBoss die Quelldateien der Beans nicht findet. Also klicken wir auf "Edit Source Lookup Path..." und fügen per "Add..." die Quellverzeichnisse des Bean- und des Web-Projekts zu.
Debug: Source Lookup Path (1)
Wir fügen eine Referenz auf ein "Java Project" zu:
Debug: Source Lookup Path (2)
Jetzt die beiden gewünschten Projekte auswählen:
Debug: Source Lookup Path (3)

Das ganze hätten wir auch erreichen können wenn wir im Contextmenü des Servers den Punkt "Open" gewählt hätten und anschließend auf "Open Launch Configuration" gegangen wären. In dem erscheinenden Dialog finden wir auf der Karteikarte "Source" den Source Lookup Path.
Debug: Source Lookup Path (4)
Auf diese Weise können wir sogar JSP-Seiten debuggen !


JBoss-Knowhow

Generierte JSP-Java-Klassen

Zu JSP-Seiten generiert der in den JBoss integrierte Tomcat 5.5 Java-Dateien, diese wiederum werden ganz normal compiliert. Die generierten Java-Dateien findet man hier: JBOSS_DIR\server\default\work\jboss.web\localhost\WEBAPP\org\apache\jsp. Ein Blick in diese Dateien ist bei Compilefehlern in der JSP-Seite nötig, da die Zeilenangaben sich auf die Java-Datei beziehen und nicht auf auf die JSP-Datei.

JMXConsole und JNDIView

Unter http://localhost:8080/jmx-console erreicht man die JMXConsole, über die JBoss seine MBeans für die interne Serververwaltung anzeigt. In der Gruppe "jboss" finden wir service=JNDIView
JMXConsole (JNDIView)
Diesen Service öffnen. Wir sehen einige Properties der MBean sowie einige Operations.
JNDIView
Uns interessiert java.lang.String list(). Wir führen sie aus indem wir auf Invoke klicken.
Die folgenden Ausgaben entstanden als das Stateless-Beispiel deployed war:
Im "Global JNDI Namespace" finden wir unsere diversen Beans (Remote- und Local-Home-Interfaces) hinterlegt:
JNDIView (Stateless-Beispiel)
Am Anfang der Seite finden wir auch den ENC (Environment Naming Context) des EJB-Moduls wieder:
JNDIView (Stateless-Beispiel)

Logging

In allen Beispielen wird das Logging mittels der Klassen des Packages java.util.logging verwendet. Im Code sieht das so aus:
Auf Klassenebene wird ein Logger deklariert (Codefragmente aus dem Stateless-Beispiel):
    protected static final Logger logger = Logger.getLogger(GeometricModelBean.class.getName());

Die Logausgabe erfolgt so:
    logger.info("computeCuboidVolume mit a = " + a + ", b = " + b + ", c = " + c);

Die Logdatei ist beim JBoss im Default in "JBOSS_DIR\server\default\log\server.log" und enthält z.B. nützliche Infos zu den EJB-QL-Abfragen.

Das Verhalten des Logger-Moduls wird über eine Property-Datei konfiguriert. Im Default ist dies "JRE_DIR\lib\logging.properties". Im folgenden der Inhalt des Sun-JDK 1.4.2_0 (Kommentare entfernt):

# Global properties

handlers= java.util.logging.ConsoleHandler

.level= INFO

# Handler specific properties.
# Describes specific configuration info for Handlers.

# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

# Limit the message that are printed on the console to INFO and above.
java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

Es wird ein Console-Logger definiert (d.h. alle Logausgaben landen auf System.out). Ein File-Handler wird zwar initialisiert, aber nicht aktiviert. Der FileHandler verwendet das XML-Format.


Um jetzt einen Logger zu aktivieren, der die Ausgabe in eine Datei umleitet und nur Ausgaben unseres Stateless-Loggers anzeigt, wird die Datei so modifiziert (am besten eine Kopie an beliebiger Stelle anlegen und diese ändern !).
# Global properties

handlers= java.util.logging.FileHandler

.level= INFO

# Handler specific properties.
# Describes specific configuration info for Handlers.

java.util.logging.FileHandler.pattern = c:/PFAD/ZUR/LOGDATEI/logdatei.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter

# Facility specific properties.
# Provides extra control for each logger.
com.knauf.ejb.level = INFO


Der Konsolen-Logger wird durch einen Datei-Logger ersetzt, der statt XML einfachen Text ausgibt. Für alle Klassen deren Package mit "com.knauf.ejb" beginnt wird das Loglevel auf "INFO" gesetzt. Würden wir hier das globale Log-Level (".level = INFO") auf einen Wert wie WARNING oder SEVERE setzen würden wir keine Ausgaben (bzw. nur noch wirkliche Fehler) aus den anderen Packages erhalten.

Dem Logger müssen wir noch erzählen wo unsere Config-Datei liegt. Dies geschieht durch das Kommandozeilenargument
-Djava.util.logging.config.file=c:/PFAD/ZUR/CONFIGDATEI/logging.properties

Für den JBoss-Server ist das Vorgehen so:
Im Default geht die Logausgabe über das java.util.logging-Package auf die Konsole.
Um den Server dazu zu bringen, diese Konfigurationsdatei zu verwenden müssen wir folgendes tun:
Rechtsklick auf einen vorhandenen Server, "Open" wählen. Es erscheint die "Server Overview".
Logging-Konfiguration (1)
Wir klicken auf "Open Launch Configuration". Auf der Karteikarte "Arguments" geben wir den Pfad zur Config-Datei an.
Logging-Konfiguration (2)
Schon haben wir die Logausgaben in der angegebenen Datei. Für den JBoss führt das erfreulicherweise sogar dazu dass NUR die Ausgaben unseres eigenen Packages in dieser Datei ausgegeben werden, die des JBoss landen weiterhin in der Standard-Datei "server.log". Dadurch haben wir alle unseren Logausgaben übersichtlich auf einem Haufen.


Bugs und Troubleshooting




Version 1.1.0.2, Stand 07.09.2006
Historie:
1.0.0.0 (25.09.2005): Erstellt
1.0.1.0 (31.10.2005): Abschnitt "Troubleshooting"
1.0.2.0 (23.11.2005): Abschnitt "JMXConsole/JNDIView"
1.0.2.1 (24.11.2005): Pfad-mit-Leerzeichen-Hinweis bei Installation
1.0.3.0 (05.12.2005): JBoss von 4.0.3 auf 4.0.3 SP1 aktualisiert
1.1.0.0 (28.12.2005): Web-Tools-Plugin von 1.0M8 auf 1.0 gebracht, Bug-Sektion zugefügt
1.1.0.1 (08.01.2006): JBoss-Plugin angepaßt (ClassPath erweitert), ohne diesen aktualisierten Plugin ist JSP-Beispiel 4 nicht compilefähig !
1.1.0.2 (15.01.2006): Link zur WTP-Update-Site.
07.09.2006: Doppelt vorhandes Bild bei XDoclet-Config (ejbdoclet statt webdoclet)
26.03.2007: Links zu gespiegelter Software enfernt.