Die erste Refcard beinhaltet die Grundlagen über Java Server Faces (JSF). Es wird der Entwicklunsprozess, der Lebenszyklus (Lifecycle), die Konfigurationsdatei faces-config.xml, die JSF Expression Language (EL) sowie die JSF Core und HTML Tags und noch einiges anderes aufgezeigt.

Die zweite Refcard beinhaltet die Gundlagen über Java Persistence API (JPA). Themen sind unter anderem das Objektrelationale Mapping, den EntityManager erhalten und verwenden, Transaktionen verwenden, Queries ausführen und noch einiges mehr.

Ich finde vor allem die JPA Refcard wirklich brauchbar. Es behandelt viele grundsätzliche Themen die man bei jedem Projekt, was mit JPA oder Hibernate durchführt, benötigt und dient dadurch wirklich als nützliche Hilfe. Man kann es auch sehr gut als Unterstützung in den Einstieg von JPA oder Hibernate verwenden, was natürlich auch für alle anderen Spickzettel gilt.

Die JSF Refcard behandelt auch viele grundsätzliche Themen, aber letztlich finde ich z.B. eine online TLD für die Tags z.b. wesentlich praktischer. Andererseits ist z.B. auch bei jedem Html Tag ein Screenshot der Komponente zu sehen, was zum Beispiel den Unterschied zwischen “h:selectOneListbox“, “h:selectOneMenu“, “h:selectManyListbox” und “h:selectManyMenu” schnell und deutlich hervorhebt. Viele verwechseln gerade bei diesen eben genannten immer gerne die Komponenten bzw. das daraus resultierende Html Ergebnis ;).

Neben den beiden hier vorgestellten Refcardz zu JSF und JPA sind schon eine Reihe anderer interessanter Spickzettel veröffentlicht worden. So findet man zum Beispiel Spickzettel zu “Dependency Injection in EJB 3“, “Design Patterns“, “Getting Started with Eclipse” oder für alle die mit RichFaces, Ajax und dadurch auch mit jQuery zu tun haben “jQuery Selectors“.

Man kann alle Refcardz auf refcardz.dzone.com herunterladen, muss allerdings leider erst registrieren. Falls sich das einer gänzlich sparen möchte schicke ich sie ihm auch gerne per Mail zu =).

Damit klar ist mit welchen Tools und deren Versionen in diesem Tutorial gearbeitet wird hier eine kurze Auflistung. Es wird später noch einmal darauf eingegangen wenn die Tools heruntergeladen werden müssen:

• Eclipse Ganymede – IDE for Java EE Developers
• JBoss Application Server Version 4.2.2.GA
• JBoss Seam Version 2.0.2
• JBoss Tools Version 3.0.0 Alpha 1
• MySQL Version 5.0.x
• MySQL GUI Tools für die Version 5.0
• MySQL Connector for Java 5.1

Sobald die Entwicklungsumgebung mit den eben aufgelisteten Tools eingerichtet ist soll noch ein kleines “Hello World Seam Projekt” mit Hilfe der JBoss Tools Plugins aus Eclipse heraus erstellt werden. Das Ergebnis wird wie folgt aussehen:

Das Tutorial ist in folgende Abschnitte unterteilt:

• Herunterladen der notwendigen Software und Tools
  • Eclipse herunterladen
  • JBoss AS herunterladen
  • JBoss Seam herunterladen
  • MySQL herunterladen
• Ordnerstruktur und Eclipse vorbereiten
  • Eclipse und Projekt Workspace
  • JBoss AS und JBoss Seam
  • Fertige Verzeichnisstruktur
  • Eclipse Startparameter und Teststart
  • JBoss Tools Eclipse Plugins installieren
• MySQL Datenbank installieren und konfigurieren
  • MySQL Installieren
  • Datenbankschema in MySQL erstellen
  • Datenbankbenutzer in MySQL erstellen
  • MySQL Connector/J Treiber dem JBoss AS bekannt machen
• Erstes Hello World Seam Projekt erstellen
  • Projektgenerierung mit Hilfe von Seam Gen
  • JBoss Seam Web Projekt erstellen
  • Erster Wizzard Dialog “Seam Web Project”
  • Zweiter Wizzard Dialog “Web Module”
  • Dritter Wizzard Dialog “JSF Capabilities”
  • Vierter Wizzard Dialog “Seam Facet”
  • Projekt Generierung
  • Generierte Projektstruktur
• Erstes Deployment und das berühmte “Hello World”
  • Deployment Angaben für den JBoss überprüfen
  • Erster Start des JBoss AS aus Eclipse heraus
  • Erfolgreicher JBoss AS Start und Deployment
  • Aufruf der Web Anwendung im Browser
  • Erstes Editieren: “Hello World” Text hinzufügen
• Fazit
  • Wie geht es weiter?

Herunterladen der notwendigen Software und Tools

Ich möchte kurz erwähnen, dass die folgenden Beschreibungen sich auf Windows beziehen. Das ist zwar generell unabhängig, allerdings sind manche Angaben Pfadabhängig und gelten in diesem Fall für eine Windows Umgebung.

Als erstes muss Eclipse besorgt werden. Dazu auf eclipse.org gehen und im Menü auf Download klicken. Die einfachste Variante ist direkt das Eclipse für Java EE Developers Package herunterzuladen. Der Vorteil liegt darin, dass das Web Tools Projekt und andere notwendige Abhängigkeiten bereits vorinstalliert sind und mit dem angebotenen Eclipse zusammenspielen.

Weil JBoss Seam ein Framework für die einfache Verbindung zwischen EJB 3 und JSF ist sollten wir uns auch den passenden Application Server besorgen. JBoss Seam kann man auch auf einem Servlet Container, wie zum Beispiel Apache Tomcat, laufen lassen allerdings benötigt man dazu das Embedded JBoss Packet.
Den JBoss AS findet man auf seiner offiziellen Seite unter jboss.org und dort wieder auf den Button Download klicken. Für dieses Tutorial wird die letzte stabile Version 4.2.2.GA verwendet. Mit der zuletzt veröffentlichten Version 4.2.3.GA wird der Seam Phaselistener doppelt installiert, was zu einem fehlerhaften Zustand führt. Aus diesem Grund wird die vorherige Version 4.2.2.GA hier verwendet.

Und nun zu dem eigentlichen Framework um das es hier geht: JBoss Seam. Auch hier wird die letzte stabile Version 2.0.2 SP1 heruntergeladen.

Als Datenbank wird die MySQL verwendet. Dazu auch hier die letzte stabile Version 5.0 herunterladen.

Sehr nützlich für die Datenbankentwicklung mit der MySQL sind die MySQL Admin GUI Tools. Auch hier die letzte Version 5.0 herunterladen.

Um später von einer Java Anwendung aus auf die MySQL Datenbank zugreifen zu können müssen noch die Connector Treiber für Java “MySQL Connector/J” heruntergeladen werden.

Ordnerstruktur und Eclipse vorbereiten

Ich persönlich bevorzuge immer einen Projektordner der zu einem Thema ausgerichtet ist und alle für dieses Thema benötigten Tools enthält, sofern das möglich ist. In diesem Tutorial soll eine JBoss Seam Entwicklungsumgebung erstellt werden und dazu wurde der Ordner D:\Projekte\JBossSeam erstellt und sämtliche Tools darunter entpackt.

Gleich als erstes wird Eclipse Ganymede entpackt. Das heruntergeladene .zip einfach direkt im Projektordner entpacken. Anschließend sollte ein Verzeichnis eclipse vorhanden sein. Nun fehlt nur noch der Eclipse Workspace um eine glückliche Eclipse Installation fertigzustellen. Alle Eclipse Projekte in dieser Umgebung sollen im workspace Verzeichnis liegen. Dieses wird gleich neben dem eclipse Verzeichnis erstellt.

Für den JBoss AS und JBoss Seam wird ein Verzeichnis mit dem Namen jboss erstellt. Darin wird das JBoss AS und das JBoss Seam .zip entpackt. Anschließend sollte in dem Verzeichnis jboss die Ordner jboss-4.2.2.GA und jboss-seam-2.0.1.GA liegen.

Die fertige Verzeichnisstruktur sieht anschließend bei mir wie folgt aus:

Zum Starten von Eclipse habe verwende ich eine start_eclipse.bat Datei um Eclipse noch ein paar Startparameter wie den Workspace oder VM Speicherangaben mitzugeben:

Die Speicherangaben sind notwendig weil unter anderem der JBoss direkt aus Eclipse heraus gestartet werden soll und Eclipse somit genügend reservierten Arbeitsspeicher zur Verfügung hat. Ist eine solche .bat Datei oder eine Verknüpfung erstellt worden, sollte gleich getestet werden ob sich Eclipse auch starten lässt.

Ist dies der Fall fehlen noch die JBoss Tools Plugins in Eclipse und die Datenbank für das erste “Hello World” mit JBoss Seam.

Mit den JBoss Tools erhält man in Eclipse eine sehr gute Unterstützung für die Entwicklung mit den verschiedensten JBoss Elementen. Besonders schätze ich die Hibernate Tools, die Seam Tools und den RichFaces Visual Editor für die Syntax Unterstützung. Mit den Seam Tools wird später das Seam Projekt erstellt. Zuvor müssen diese allerdings erst installiert werden.
Bis vor kurzem mussten die einzelnen JBoss Tools Plugins noch als Nightly Build unter Eclipse Ganymede installiert werden. Seit ein paar Tagen ist allerdings die erste Version der JBoss Tools 3.0.0 (Alpha 1) veröffentlicht worden und man kann diese nun über den Eclipse Update Manager installieren.

Eclipse starten und im Hauptmenü unter “Help->Software Updates…->Available Software Tab->Add Site…” die JBoss Tools Development Update Seite http://download.jboss.org/jbosstools/updates/development hinzufügen.
Anschließend aufklappen und folgende im Screenshot sichtbar JBoss Tools Plugins selektieren:

Die Installation mit dem Button “Install…” starten, der Lizenz zustimmen und Eclipse nach der erfolgreichen Installation neu starten.

Wer eine ausführliche Beschreibung der Installation dieser 3.0.0 Alpha 1 Version sowie Schreenshots der neuen Features sehen möchte sollte sich den Artikel “JBoss Tools 3.0.0 Alpha1 – langsam geht es vorwärts” anschauen.

MySQL Datenbank installieren und konfigurieren

Die MySQL kann auf verschiedene Arten installiert werden. Ich verwende immer das Installationsprogramm und habe für meine Entwicklung eine MySQL Systemweit als Windows Dienst installiert. Den Dienst starte ich immer von Hand, wenn ich ihn benötige. Arbeitet man jeden Tag in dieser Umgebung kann man die Datenbank auch automatisch starten lassen.

Bei der Installation der Datenbank ist nichts zu beachten außer, dass man ein Passwort für seinen root User vergeben sollte an das man sich erinnert ;).
Anschließen noch die MySQL GUI Tools installieren. Ist beides Installiert kann man die Installation testen indem die Datenbank gestartet und sich über den MySQL Administrator (eines der GUI Tools) mit dem Benutzer root und dem vergebenen Passwort verbunden wird:

Es wird für das “Hello World Seam Projekt” eine Datenbank benötigt auf die wir vollen Zugriff haben. In MySQL muss dazu ein neues Schema erstellt werden. Am einfachsten und schnellsten geht das über das MySQL Administrator GUI Tool. Diesen also starten und sich als root auf localhost einloggen (Vorher natürlich noch MySQL starten).
Um ein neues Schema zu erstellen auf “Kataloge” klicken und anschließen darunter in der Liste der Schemata aus dem Context Menü (rechte Maustaste) “Neues Schema anlegen” selektieren.

Ich habe es seamprojekt genannt. Das neu erstellte Schema wird nun neben den anderen aufgelistet.

Nun fehlt noch der Benutzer für die Datenbankverbindung. Dazu auf den Punkt “Benutzerverwaltung” klicken und den Button “Neuen Nutzer anlegen” klicken (ist am unteren Rand zu finden). Username und Passwort vergeben – bei mir heißt hier seamdb mit dem Passwort seam – und den Button “Anwenden” drücken.

Als letztes müssen dem eben erstellten User noch die notwendigen Rechte vergeben werden. Dazu in dem User editieren Panel bleiben und das Tab “Schema-Berechtigungen” selektieren. Dort das zuvor erstellte Schema seamprojekt selektieren und sämtliche Rechte zuweisen. Das ganze mit dem Button “Anwenden” abschließen.

In einer Produktivumgebung vergibt man die Rechte natürlich selektiver – hier geht es lediglich um ein Testprojekt und erste Schritte mit Seam.

Damit der JBoss später von der deployten Anwendung aus auf die MySQL Datenbank zugreifen kann muss er den Datenbank Treiber im Classpath finden.
Dazu das heruntergeladene MySQL Connector/J Zip entpacken und das darin liegende mysql-connector-java-5.1.6-bin.jar in das lib Verzeichnis der JBoss Default Server Instanz legen (D:\Projekte\JBossSeam\jboss\jboss-4.2.2.GA\server\default\lib).

Nun ist die MySQL Datenbank und der JBoss soweit vorbereitet, dass es endlich an das erste Projekt gehen kann.

Erstes Hello World Seam Projekt erstellen

Nun gelangen wir endlich zu dem interessanten Teil: das “Hello World Seam Projekt” wird erstellt. Um ein solches Projekt zu erstellen bietet das JBoss Seam Framework uns die Möglichkeit das Grundgerüst eines Seam Projektes generieren zu lassen, was wir natürlich der Einfachheit halber ausnutzen wollen.

Seam liefert eine ziemlich coole Projektgenerierung mit dem Namen Seam Gen (seam-gen.bat) von Haus aus mit. In diesem Tutorial soll nicht mit Seam Gen ein Eclipse Projekt erstellt werden sondern mit den JBoss Tools Plugins, die einen Projekt Wizzard für Eclipse mitbringen. Wer einen Blick auf Seam Gen werfen möchte der kann dazu auch die ausführliche Anleitung aus der offiziellen Seam Dokumenation in Kapitel 2 lesen.

Noch ganz kurz zu dem elementaren Unterschied zwischen Seam Gen und den JBoss Tools Plugins: Mit Seam Gen wird ein einzelnes, erst einmal IDE unabhängiges, Projekt erstellt welches alle drei Teilbereiche (Web, EJB, EAR) sowie die Teststruktur in einem Ordner hält. Zusätzlich wird ein universelles Ant Build File für das Deployment, Erzeugung von neuen Seam Komponenten und Tests erstellt. Man kann später noch auswählen ob eine Projektstruktur für Eclipse oder Netbeans erstellt werden soll. Generell arbeitet man aber dennoch IDE unabhängig mit dem Ant Build File.

Das Utility “Seam Gen” befindet sich im Seam Verzeichnis unterhalb des Ordners seam-gen. Bei uns ist es somit im Verzeichnis “D:\Projekte\JBossSeam\jboss\jboss-seam-2.0.1.GA\seam-gen” zu finden.

Mit den Seam Tools Eclipse Plugin werden drei Einzelprojekte (Web, EJB, EAR) erstellt die zusammen ein ganzes ergeben. Das Testprojekt wird als viertes, auch separat liegendes Projekt, erzeugt, welches auf die anderen referenziert. Mehr zu dieser Projektstruktur sehen wir später noch. Arbeitet man also mit den Seam Tools legt man sich von vornherein auf die Eclipse als IDE fest und bekommt kein ANT Build File erstellt. Man deployt, erstellt und testet direkt aus Eclipse heraus.

Weil für die Projektgenerierung nicht das Batch File seam-gen.bat sondern das durch die Seam Tools verfügbare Eclipse Projekt Wizzard ist es wichtig, dass die JBoss Tools Plugins korrekt installiert wurden. Ist das der Fall kann eine JBoss Seam Perspektive in Eclipse ausgewählt werden.

In der Seam Perspektive stehen über das Hauptmenü (File->New) verschiedene Möglichkeiten für die Erstellung von Seam Komponenten (Action, Entity, Conversation, …) und einem Seam Web Projekt zur Verfügung. Wir selektieren natürlich die Auswahl “Seam Web Projekt“.

Es öffnet sich ein Projekt Wizzard mit dem ersten Dialog unter dem Namen “Seam Web Project” in dem schon einiges angegeben werden muss. Als erstes wird der Projektname vergeben – in diesem Beispiel soll das Projekt “HelloWorldSeamProjekt” benannt werden.

Als nächstes muss eine Server Runtime Target konfiguriert werden, wie auch im Dialog mit der Fehlermeldung “Target Runtime cannot be emtpy” angezeigt wird.

Um eine neue Server Runtime Target zu erstellen rechts neben der “Target Runtime” Auswahl auf den Button “New…” klicken um den JBoss AS 4.2 als Target Runtime zu selektieren.
In diesem Dialog werden unter zwei Ordnern JBoss AS Server Versionen angeboten. Wir verwenden “JBoss, a division of Red Hat” denn dieser wird durch die JBoss Tools mitgeliefert. Es muss natürlich die “JBoss 4.2 Runtime” selektiert werden und das Häckchen bei “Create a new local server” wird auch noch gesetzt. So ersparen wir uns später diesen Schritt.

Anschließend auf den Button “Next >” drücken. Im zweiten Schritt muss das Home Verzeichnis angegeben werden indem der JBoss AS liegt. Bei uns liegt er wie oben beschrieben unter “D:\Projekte\JBossSeam\jboss\jboss-4.2.2.GA”.

Button “Next >” drücken. Im letzten Schritt wird der Fehler “Deploy folder not specified” angeben, welcher ignoriert werden kann, denn das Deploy Directory ist ordentlich für die Default JBoss Server Instanz angegeben. Der Target Runtime Wizzard kann somit mit dem Button “Finish” beendet werden.

Man gelangt wieder in den ersten Dialog “New Seam Project” und die eben konfigurierte Target Runtime wurde angegeben. Auch der Target Server wurde durch das Setzen der Checkbox “Create a new local server” im Target Runtime Dialog unter dem Namen “JBoss 4.2 Server” erstellt und nun selektiert.

Als nächstes muss die “Dynamic Web Module version” ausgewählt werden. Wir verwenden die Version 2.5, welche wahrscheinlich auch schon vorselektiert wurde.

Die letzte wichtige Konfiguration auf diesem Dialog ist der letzte ganz unten unter “Configuration”. Dort muss “Dynamic Web Project with Seam 2.0″ selektiert sein.

Der fertig konfigurierte Dialog sieht anschließend wie folgt aus:

Mit dem Button “Next >” diesen ersten Dialog verlassen und in den nächsten Schritt gehen um das Web Modul zu konfigurieren.

In diesem zweiten Dialog “Web Module” kann angegeben werden unter welchem Context Root (Teil der Url: http://localhost:8080/) die Web Anwendung erreichbar sein soll. Ich persönlich verwende an dieser Stelle immer den Projektnamen und lass die Default Einstellung so stehen.
Die zweite Angabe ist das “Content Directory”. Die Default Angabe ist immer “WebContent” – ich änder das immer auf “web” ab. Aber das ist Geschmackssache. Das “Content Directory” ist im Web Projekt der Ordner unter dem die .xhtml Dateien, der /META-INF Ordner und die web.xml liegen.
Das “Java Source Directory” bleibt auf “src” und die Checkbox für “Generate deployment descriptor” ist selektiert.

Mit dem Button “Next >” diesen Dialog beenden und in den nächsten Schritt gehen um die JSF Einstellungen zu konfigurieren.

In diesem Dialog bleibt alles so wie vorgegeben.

Somit direkt mit dem Button “Next >” weitergehen um Seam zu konfigurieren.

In diesem Dialog “Seam Facet” muss die “Seam Runtime” angegeben werden wie auch die Fehlermeldung “Seam Runtime is not selected” aufzeigt.

Zuerst muss die Seam Runtime erstellt und konfiguriert werden.

Den Button “Add…” drücken um in einen Unterdialog für die Seam Runtime Konfiguration zu gelangen. In dem “Seam Runtime” Dialog den “Seam Home Folder”, also das Seam Verzeichnis, angeben. Bei uns liegt dieser neben dem JBoss AS unter “D:\Projekte\JBossSeam\jboss\jboss-seam-2.0.1.GA“.

Den Unterdialog mit dem Button “Finish” beenden.

Anschließend ist die “Seam Runtime” konfiguriert und da wir ein EAR Projekt erstellen wollen muss der EAR Radio Button noch selektiert werden.

Nachdem die Seam Runtime nun konfiguriert ist wird bemängelt, dass noch kein “Connection Profile” selektiert ist.

Um ein “Connection Profile” selektieren zu können muss erst einmal eines erstellt werden. Dazu zuerst unter “Database Type” die MySQL “MySQL 5 (InnoDB)” heraussuchen und selektieren. Anschließend neben der noch leeren “Connection Profile” Angabe den Button “New…” drücken. Es erscheint ein neuer Connection Profile Wizzard.
Darin den Connection Profile Type “MySQL” selektieren und einen Namen, z.B. “Lokale MySQL”, dafür vergeben.

Mit dem Button “Next >” in den nächsten Schritt gehen um den MySQL Treiber zu konfigurieren.
Es wird verlangt, dass man einen Treiber definiert und selektiert.

Dazu rechts neben der leeren Treiber Selektbox auf den Button (ist nur ein rundes gebliches Bild) “New Driver Definition” klicken. Anschließend im ersten Reiter “Name/Type” den Namen und Typ der MySQL angeben. Wir verwenden eine “MySQL 5.0″.

Im zweiten Reiter “Jar List” muss nun der MySQL Connector/J Treiber selektiert werden. Dazu erst den voreingetragenen Wert mit dem Button “Clear All” entfernen und anschließend mit dem Button “Add Jar/Zip” den im JBoss Default Server abgelegten MySQL Connector/J Treiber mysql-connector-java-5.1.6-bin.jar hinzufügen. Zur Erinnerung: der Treiber wurde im Projektordner im JBoss AS Verzeichnis abgelegt (D:\Projekte\JBossSeam\jboss\jboss-4.2.2.GA\server\default\lib).

Den Dialog mit “OK” beenden.
Anschließend können die Daten für die bereits eingerichtete Datenbank seamprojekt (url: jdbc:mysql://localhost:3306/seamprojekt ) angegeben (user: seamdb & pw: seam) werden.

Mit dem Button “Test Connection” kann die konfigurierte Verbindung getestet werden. Die Prüfung sollte positiv mit einer “Ping succeeded!” Meldung enden.

Wenn dem nicht so ist sollte überprüft werden ob die Datenbank generell läuft (MySQL Administrator), ob der User und das Passwort richtig vergeben sind (man kann sich z.B. mit dem MySQL Query Browser gegen die Datenbank mit dem User verbinden) und ob die Angaben in dem Dialog korrekt eingegeben wurden.

Funktioniert die Datenbankverbindung kann der Dialog mit “Finish” beendet werden.
Nun ist das Connection Profile eingerichtet und als letztes muss noch das Datenbank Schema angegeben werden. In unserem Fall heißt es wie die konfigurierte Datenbank selbst: “seamprojekt”.

Der letzte in diesem Dialog zu konfigurierende Punkt sind die Package Vorgaben für die Code Generation. Wenn das Projekt erstellt wird, werden initial einige Java Klassen erstellt. Die hier konfigurierten Package Namen werden dafür verwendet. Aber auch für die später über die verfügbaren Seam Dialoge (File->New…) erstellten Klassen werden diese Angaben hier verwendet. Aus diesem Grund sollten wir sie also richtig anpassen. Man kann als Package Namen verwenden was man möchte – ich nehme natürlich de.javathreads.helloworldseamprojekt (Java Packages sollten übrigens klein geschrieben werden).
Mein vollständiges Dialogfenster mit konfigurierter Seam Runtime, dem Connection Profile und den Package Angaben sieht nun wie folgt aus:

Den Projekt Wizzard mit dem Button “Finish” beenden.

Das “Hello Word Seam Projekt” EAR Projekt wird nun automatisch erstellt und mit allen Grundkonfigurationen versehen.

Es werden insgesamt vier Teilprojekte von den Seam Tools erstellt. Dabei sind drei für das EAR Projekt direkt relevant und das letzte ist ein Projekt für die Unit Tests.

Erstes Deployment und das berühmte “Hello World”

Nachdem nun die Entwicklungsumgebung eingerichtet ist und das Projekt scheinbar ordentlich erstellt wurde kann man es direkt auf den JBoss AS deployen. Es wurde ein lauffähiges EAR Projekt mit der Verwendung von Hibernate, Sun JSF-RI 1.2, RichFaces und Facelets erstellt und vorkonfiguriert. Das Projekt müsste eigentlich auch automatisch dem konfiguriertem JBoss Server für das Deployment hinzugefügt worden sein.

Aber es lohnt sich das noch einmal selbst kurz zu überprüfen. Um das Projekt auf dem JBoss zu deployen muss die JBoss Server View geöffnet werden. Diese sollte sogar schon sichtbar sein ansonsten über das Hauptmenü die JBoss Server View öffnen: “Windows->Show View->Other…->Server->JBoss Server View”. Um das Projekt dem Server für das Deployment bekannt zu machen mit der rechten Maustaste auf den Server klicken und “Add and Remove Projects…” selektieren.

Anschließend ist ein Dialog zu sehen in dem auf der linken Seite alle für ein Deployment verfügbaren Projekte und rechts alle Projekte die auf diesem JBoss deployt werden sollen zu sehen. In unserem Fall sieht man das HelloWorldSeamProjekt.ear und eine Datasource Konfiguration HelloWorldSeamProjekt-ds.xml. Diese Datei muss mit auf den JBoss deployt werden weil es die Datenkbankkonfiguration für unser Hello World Projekt enthält. Auf einem JBoss werden die Datenbankkonfigurationen in einem bestimmten XML Format in die Server Instanz gelegt und somit bekannt gemacht.
Der Dialog kann mit Finish beendet werden und anschließend ist das Projekt und die Datasource unter JBoss 4.2 sichtbar.

Der JBoss kann nun gestartet werden. Dazu mit der rechten Maustaste auf den JBoss 4.2 Server->Start oder den Server selektieren und den grünen runden Start Button in der Server View drücken. Unter Windows kann es passieren, dass man gefragt wird ob der Server oder Java weiterhin geblockt werden sollen aber wir erlauben natürlich die Ausführung dieser Programme.

Ist der Server einmal gestartet so steht als Status “Started”, was noch nicht bedeuten muss, dass dieser auch erfolgreich gestartet ist.

In der Console sind die Log Ausgaben des JBoss Servers zu sehen. Man sollte die Logausgaben des JBoss AS immer auf Fehler überprüfen. Dazu die Console View selektieren und einmal komplett nach oben scrollen um sich zu vergewissern, dass keine Exception während des Starts geworfen wurde.

Bei mir kam z.B. beim ersten Start folgende Exception:

Und Tatsächlich hatte sich in meiner Datasource Konfiguration in dem Passwort ein falsches Zeichen am Ende eingeschlichen (das PW lautet nur “seam” und nicht “seamd”). Die Datasource Konfiguration HelloWorldSeamProjekt-ds.xml befindet sich übrigens im EAR Projekt HelloWorldSeamProjekt-ear unterhalb des resources Ordner:

  
    HelloWorldSeamProjektDatasource
    jdbc:mysql://localhost:3306/seamprojekt
    com.mysql.jdbc.Driver
    seamdb
seamd
  

Das falsche Zeichen habe ich nun entfernt und den Server neu gestartet.

Nun ist dieser ohne Exceptions zu werfen, wie es auch sein sollte, hochgefahren und gestartet. Das korrekte Deployment kann in der Console nachgeprüft werden. Die letzte Zeilen sagen aus, dass das Projekt deployt wurde und der Server erfolgreich gestartet ist.

Alle deployten Anwendungen werden, wie weiter oben in dem Server Runtime Environment konfiguriert, in die JBoss Default Server Instanz deployt. Im Jboss liegen alle Anwendungen im Verzeichnis default unterhalb des JBoss Server Instanz Verzeichnisses. Unsere eben deployte Anwendung befindet sich somit im Verzeichnis D:\Projekte\JBossSeam\jboss\jboss-4.2.2.GA\server\default\deploy, wie auch der Screenshot zeigt:

Der lokale JBoss bzw. dessen Management Konsole ist per Default unter dem Port 8080 erreichbar. Mit der Adresse http://localhost:8080 gelangt man somit auf die Einstiegsseite des lokalen JBoss AS:

Und der Aufruf zu dem generierten “Hello World Seam Projekt” ist unter der URL http://localhost:8080/HelloWorldSeamProjekt erreichbar:

Als letztes fehlt uns noch zu unserem Glück der eigentliche “Hello World” Text. Dazu öffnen wir im Visual Page Editor, welcher per default für die Dateien mit der Endung .xhtml unter Eclipse verknüpft ist, die home.xhtml. Diese Datei befindet sich im Web Projekt, welches das einzige Projekt ohne Zusatz ist und als Icon eine Weltkugel über dem Ordner hat. Alternativ kann natürlich auch mit STRG-SHIFT-R der “Open Resource” Dialog geöffnet werden um die Datei zu öffnen.

Speichert man die Änderungen startet das Hot Deployment der geänderten Dateien auf den JBoss AS. Per default wird das Hot Deployment erst nach 15 Sekunden durchgeführt.

Anschließend im Browser F5 drücken oder in der Adressleiste noch einmal die URL aufrufen und das eben erstellte “Hello World” erscheint.

Fazit

Obwohl es viel und evtl. sogar kompliziert aussieht werden diejenigen, die ein solches Projekt schon einmal von Hand aufgesetzt und konfiguriert haben merken, dass es nun wesentlich schneller und einfacher ging. Vor allem für einen schnellen Einstieg in die Entwicklung eines JBoss Seam JEE5 Projektes aber auch für ein gewöhnliches Web Projekt ist dieser Weg sehr bequem.
Hat man diesen Projekt Wizzard erst einmal initial konfiguriert kann man bereits konfigurierte Teile für die Erstellung eines nächsten Projektes wiederverwenden.
Ist man erst einmal vertraut mit dem Projekt Wizzard erstellt man ein neues Projekt binnen ein paar Minuten.

Meiner Meinung nach ist der größte Vorteil der, dass verschiedenen Frameworks wie Facelets, JBoss RichFaces, JBoss Seam und JSF 1.2 RI bereits so konfiguriert sind, dass sie miteinander arbeiten. Unerfahrene Leute benötigen allein an der Konfiguration für das Zusammenspiel der einzelnen Frameworks sehr viel Zeit.

Wer mit JBoss Seam, JBoss RichFaces, Facelets oder gar JSF generell noch nicht vertraut ist sollte damit Anfangen das generierte Projekt zu erkunden und damit herumspielen. Das fängt bei der Verwendung von Facelets mit dem Template und Tags an, geht über die Verwendung der RichFaces Komponenten bis hin zu Ajax, dann kommt JBoss Seam mit seinen verschiedenen Komponenten (Authentifizierung, EntityQuery, EntityHome, Scopes) bis zuletzt zu der Verwendung von JEE 5 Technologien wie EJB 3.0 und JPA/Hibernate für die Persistierung.
Man kann allein bei dem generiertem Projekt viel lernen und ausprobieren. Viel kaputtmachen kann man nicht denn zur Not erstellt man sich das Projekt einfach schnell noch einmal neu.

Wer sich mit den Technologien auskennt sollte das Projekt nach seinem Geschmack anpassen wie z.b. das erstellen des Domänenmodells, Packages anpassen, Testprojekt aufsetzen usw..

Insgesamt sollte dieses Tutorial nur aufzeigen wie man in ein solches Projekt für JBoss Seam aufsetzen kann und mein Fazit darüber ist, dass es noch nie so einfach war ein solches Projekt zu starten bzw. sich zu erstellen.
Ich werde wohl in Zukunft noch des öfteren auf diese Tutorial Bezug nehmen – vor allem wenn ich einzelne Teile von Seam oder sonstiger JSF Entwicklung beschreiben werde.

Viel Spass beim ausprobieren!

Um JMX zu nutzen werden sogenannte MBeans (Managed Beans) erstellt welche über einen Adapter, wie zum Beispiel einen HTTP Adapter, über den Web Browser zugänglich gemacht werden. Mit Java 5 kommt auch noch die Möglichkeit auf die JConsole zu verwenden um auf MBeans zuzugreifen. Mehr zu den Grundlagen der Java Management Extension auch in der online Ausgabe Java ist auch eine Insel – Kapitel 23.

Der JBoss AS (Application Server) steuert seine Konfigurationen über einen eigenen JMX Bus und bietet dazu eine Menge an MBeans an – siehe dazu auch aus dem JBoss AS Guide – Kapitel 2 – The JBoss JMX Microkernel. Weil die JMX Unterstützung eine Kernkomponente für den JBoss ist bietet er einfache Möglichkeiten an diese Infrastruktur für die eigenen Zwecke zu verwenden. Wie man diese am einfachsten verwenden und selbst eine JMX MBean schreiben kann soll im folgenden gezeigt werden.

Dieser Artikel ist in die folgenden Abschnitten unterteilt:

• Verschiedene Arten der JBoss MBean Services
• JBoss Service POJO
• JMX Konsole – Management Interface mit XML beschreiben

Möchte man eine JMX Bean für die eigene Anwendung, welche auf dem JBoss AS (Application Server) läuft, schreiben so bietet JBoss mehrere Möglichkeiten an. Folgende drei Möglichkeiten bestehen eine MBean für die JMX Konsole zu implementieren und zu registrieren:

• JBoss Standard MBean
• JBoss XMBean
• JBoss Servie POJO

Obwohl ich nur auf die dritte und letzte Möglichkeit eingehen möchte, werden vorab die beiden anderen Varianten kurz erwähnt, so dass man diese einordnen kann.

Für die erste Variante implementiert man einen JBoss MBean Service (auch Standard MBean genannt). Dazu erstellt man ein Interface welches sich von org.jboss.system.ServiceMBean sowie eine Klasse die dieses Interfaces implementiert. Diese MBean Service Klasse ist selbst von der Klasse org.jboss.system.ServiceMBeanSupport abgeleitet ist. Diese Klasse wird nun in der Datei jboss-service.xml als MBean konfiguriert und so dem JBoss AS bekannt gemacht.
Ein kleines “Hello World Service” Tutorial für das Erstellen eines solchen JBoss MBean Services findet sich im JBoss Wiki.

Die zweite Variante basiert auf der eben vorgestellten, nur dass die MBean über das JBoss XMBean Framework seine Metadaten beschreibt. An dieser Stelle kommt die Möglichkeit einfache POJOs als MBeans zu verwenden ins Spiel und es ist nicht mehr notwendig das oben beschriebene Interface ServiceMBean zu implementieren oder andere Regeln in der MBean Klasse einzuhalten. Allerdings wird für diese sogenannte XMBean Deployment Descriptor in Form eines XML Dokuments benötigt. Aus diesem Grund heißt diese MBean XMBean.
In diesem Deplyoment Descriptor können sämtliche Attribute, Methoden und deren Parameter beschrieben werden. Ein weiter Vorteil war die Möglichkeit Interceptor-Methoden zu implementieren. Diese konnte man zum Beispiel für Sicherheitsüberprüfungen bei Methodenaufrufe verwenden. Eine schöne ausführliche Beschreibung der XMBean findet sich auf dem Blog von organig thoughts.

Die hier eben kurz erwähnten Wege eine JBoss MBean bzw. XMBean (beides sind JMX MBean) zu erstellen können auch noch einmal in der offiziellen JBoss Server Configuration Guide im Kapitel 3.4.3 mit dem Titel “Writing JBoss MBean Services” nachgelesen werden.

Die dritte Variante ist die in diesem Artikel eigentlich fokussierte Variante mit dem Namen JBoss Service POJOs.

Die einfachste Variante eine JBoss MBean für die JMX Konsole zu erstellen ergibt sich durch die JBoss eigene @org.jboss.annotation.ejb.Service Annotation. Diese Annotation @Service definiert im JBoss einen Service der als Singleton, also nur mit einer Instanz (Singleton), verfügbar ist. So ergibt sich der erste Schritt daraus, einen solchen Service zu erstellen.

import org.jboss.annotation.ejb.Service;

@Service(objectName="MyApplication:service=MyService")
public class MyServiceMBean {

}

Noch einmal: die Besonderheit an dieser Service Bean besteht darin, dass auf dem Server nur eine Instanz davon besteht. Im Gegensatz zu EJB Services ist ein MBean Service nicht gepoolt, behält seinen Status (stateful) und hat application-scope. Letztlich ist dies aber eine normale Session Bean, von der lediglich nur eine Instanz besteht. Man arbeitet somit in dem Context der Anwendung und kann auf alle konfigurierten Resourcen, wie z.b. den EntityManager oder andere EJBs, zugreifen.

Um diese Service EJB nun noch JMX fähig zu machen und sie an einem MBean Server anmelden zu können, muss nun noch ein Management Interface erstellt und der Service Bean durch die @org.jboss.annotation.ejb.Management Annotation bekannt gemacht werden.

Hier das Management Interface, welche die Getter und Setter für das Attribut “lastWrittenText” sowie die Service-Methode printOut() deklariert, die später über die JMX Konsole aufgerufen werden können.

public interface MyManagementInterface {

  public String getLastWrittenText();
  public void setLastWrittenText(String lastWrittenText);

  void printOut(String text);
}

Die erstellte Service MBean “MyServiceMBean” muss dieses Interface nun noch implementieren und zudem das gleiche Interface durch die @Management Annotation bekannt machen. Erst durch diese @Management Annotation wird der JBoss aus den beschriebenen Attributen und Methoden eine Service MBean erstellen und registrieren. Im folgenden der vollständige Source Code für den POJO Service “MyServiceMBean“:

import org.jboss.annotation.ejb.Management;
import org.jboss.annotation.ejb.Service;

@Service(objectName="MyApplication:service=MyService")
@Management(MyManagementInterface.class)
public class MyServiceMBean implements MyManagementInterface {

  private String lastWrittenText;

  public void printOut(String text) {
    System.out.println("Given text: " + text);
    lastWrittenText = text;
  }

  public String getLastWrittenText() {
    return lastWrittenText;
  }

  public void setLastWrittenText(String lastWrittenText) {
    this.lastWrittenText = lastWrittenText;
  }
}

In dem Code ist zu sehen, das bei der @Service Annotation noch ein Objektname zu finden ist. Dieser dort definierte Name erscheint nach dem Starten des JBoss und dem erfolgreichem deployen der Anwendung in der JMX Konsole (Aufzurufen durch http://localhost:8080/jmx-console/). Im folgenden Screenshot findet man die definierten Namen wieder:

Selektiert man diesen Service gelangt man in die Service View, in der man alle Attribute und Methoden des Services sehen und aufrufen kann. In diesem Beispiel soll die Methode printOut(String) aufgerufen werden:

Nach der Eingabe des Methodenparameters “test string” und dem anschließenden Klicken des Buttons “invoke” erscheint auch, wie erwartet, der übergebene Text in der Server Konsole:

Leider hat man durch die Verwendung der Annotationen keine Möglichkeit die Service Bean, Attribute, Methoden oder Paramter zu beschreiben, wie es bei der ursprünglichen XMBean Variante noch als großer Vorteil angepriesen wurde.
Die gute Nachricht ist, dass auch hier eine Möglichkeit besteht diese Beschreibungen zu liefern. Der Nachteil an der Sache ist, man muss wieder auf eine XML Beschreibung zurückgreifen. Und zwar kommt wieder der XML Deployment Descriptor der XMBeans ins Spiel. Man kann genau diesen in der @Service Annotation angeben.

@Service(objectName="MyApplication:service=MyService",
		 xmbean="resource:META-INF/myService-xmbean.xml")
public class MyServiceMBean  implements MyManagementInterface {
  ...
}

Wichtig ist, dass die @Management Annotation entfernt werden muss weil nun wieder der XMBeans Deployment Descriptor die Beschreibung der MBean übernimmt. In diesem Beispiel heißt der Deployment Descriptor myService-xmbean.xml und liegt im META-INF Ordner, direkt neben der persistence.xml Datei. Wenn die Datei nicht gefunden wird schmeißt der JBoss AS während des Startens Exceptions, so dass der Fehler schnell bemerkt wird.

Der XMBeans Deployment Descriptor myService-xmbean.xml sieht für die oben gelistete POJO Service Klasse wie folgt aus:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mbean PUBLIC "-//JBoss//DTD JBOSS XMBEAN 1.0//EN"
  "http://www.jboss.org/j2ee/dtd/jboss_xmbean_1_0.dtd">


  javathreads.de - MyService MBean Beschreibung

  de.webthreads.tippit.mgmt.MyServiceMBean

  
  
    Der zuletzt ausgegebene Text wird hier gehalten.
    LastWrittenText
    java.lang.String
  

  
  
    Methode um einen Text auf der Konsole auszugeben.
    printOut

      Der Text der ausgegeben werden soll.
      text
      java.lang.String
    
    void
  

In der XML Datei sind die Beschreibungen für das Attribut sowie der Methode zu sehen. Die DTD des mbean Elements sieht wie folgt aus:

Schaut man sich jetzt die JMX Konsole an sind die Beschreibungen nun auch vorhanden, wie man im folgenden Screenshot sehen kann:

Ich habe in diesem Screenshot mal die Abhängkigkeit zur XMBean hervorgehoben. Vergleicht man diese Zeile mit dem Screenshot der JMX MBean View der MBean, die mit der @Management erstellt wurde, so sieht man dort die Zeile: MBean Java Class: de.javathreads.jbosstest.mgmt.MyManagementInterface

Auch so kann man also erkennen welcher Weg gegangen wurde um eine MBean für die JMX Konsole zu erstellen.

Insgesamt war das Erstellen einer solchen Service MBean im JBoss so einfach, dass ich es hier kurz dokumentieren musste =). Der Weg dahin hat doch etwas länger gedauert aber dadurch bin ich über einige interessante Seiten gestolpert, wie zum Beispiel das JBoss Wiki – JMX FAQ oder das wirklich gute Tutorial von JBoss Trailblazer. Nach dem lesen und googeln habe ich es ausprobiert und es hat tatsächlich (fast) auf Anhieb funktioniert.
Und jetzt während ich diesen Artikel fast zu Ende geschrieben habe entdecke ich noch eine Blitzanleitung auf dem Blog von Christian Ullenboom (Author von Java ist auch eine Insel) mit einer Schnelleinführung..

Und gerade weil das Erstellen eines solchen JMX MBean Service eigentlich so einfach ist sollten diese Erkenntnisse hier festgehalten werden.