Inhalt

• Benötigte Komponenten

• WildFly 18
• Eclipse-Tuning
• Eclipse-Codeformatter
• Javadoc
• Projektstruktur
• Debugging

• Verzeichnisstruktur
• Standalone/Domain
• JBoss starten/stoppen
• Command Line Interface (CLI)
• Web-Console
• Deploy
• Generierte JSP-Java-Klassen
• JNDIView
• JNDI-Namen
• Logging

Installation JBoss/Eclipse

Benötigte Komponenten

• JDK 1.8.0 (http://www.oracle.com/technetwork/java/index.html) installieren.
  
  
• JBoss/WildFly (http://www.wildfly.org/): die meisten meiner Beispiele basieren aktuell auf WildFly 18.0.0 Final. Download: http://wildfly.org/downloads/
  
  Snapshots von WildFly finden sich hier: https://ci.wildfly.org/viewType.html?buildTypeId=WF_Nightly (auf dem Anmeldebildschirm auf "Log in as guest" klicken)
  
  
• Eclipse IDE 2019-12 (http://www.eclipse.org/).
  Man verwendet die Version "Eclipse IDE for Enterprise Java developers" von http://www.eclipse.org/downloads/ - dort findet man aber nur den Installer als direkten Link. Erst auf dieser Unter-Seite findet man die einzelnen Download-Pakete, u.a. auch "Eclipse IDE for Enterprise Java Developers".
  
  
• JBoss Tools
  Für die Integration des JBoss Server in Eclipse verwenden wir die JBoss Tools (http://www.jboss.org/tools ), aktuell in Version 4.13.0.Final (https://tools.jboss.org/downloads/jbosstools/2019-09/4.13.0.Final.html)
  
  Die in vorherstehendem Link genannte Seite wird in Eclipse als Update-Seite zugefügt: unter "Help" den Punkt "Install new Software" aufrufen:
  
  Dort wird eine neue Update-Seite zugefügt - die steht auf der oben verlinkten JBoss Tools-Seite. Aktuell ist dies http://download.jboss.org/jbosstools/photon/stable/updates/:
  
  Im nächsten Schritt wählen wir uns nur die Komponenten aus, die für uns relevant sind (man könnte hier aber auch alles installieren). Sie sind zu finden in der Kategorie "* Abridged JBoss Tools":
  
  
  

Eclipse und WebTools-Plugin konfigurieren

WildFly 18.0.x

In "Window" -> "Preferences..." gehen und links in der Übersicht den Punkt "Server" -> "Runtime Environments" wählen. Über "Add..." einen neuen Server zufügen.

Im Bereich "JBoss Community" wählen einen Server vom Typ "WildFly 18.x Runtime"" aus.

Im nächsten Schritt als Runtime JRE ein Execution Environment "JavaSE-1.8" auswählen (sollte standardmäßig verfügbar sein, wenn Java 1.8 auf dem Rechner installiert ist) und als "Home directory" das Wurzel-Verzeichnis des JBoss auswählen.

Eclipse-Tuning

Folgende Einstellungen empfehle ich, um Eclipse schneller und Resourcenschonender einzustellen:

Automatischen Build ausschalten
Die Option "Build Automatically" im Menü "Project" wird ausgeschaltet:

Das bedeutet dass man das Compilieren vor einem Deploy per Hand durch "Build Project" bzw. "Build All" anstoßen muss.

Rechtschreibprüfung abschalten
Die integrierte Rechtschreibprüfung (per Default sowieso nur englisches Wörterbuch) wird abgeschaltet da dies sehr viele Resources kostet:

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.

Ich bevorzuge öffnende Klammern auf der gleichen Spalte wie die schließende Klammer, also viele Zeilenumbrüche.

Passend zu den Zeilenumbrüchen vor öffnenden Klammern mag ich sie auch nach schließenden Klammern.

Die maximale Zeilenlänge bis zu einem vom CodeFormatter erzwungenen Zeilenumbruch würde steht in neueren Eclipse-Versionen schon auf einem sinnvollen Default-Wert von "120":

Angewendet werden diese Einstellungen automatisch beim Tippen. Man kann aber auch nachträglich eine Datei formatieren, indem man sie öffnet und im Editor-Contextmenü den Punkt "Source" - "Format" wählt:



Für die Formatierung von HTML-/JSP-Seiten finden wir die Formatierungseinstellungen unter "Window" -> "Preferences" -> "Web" -> "HTML" -> "Editor". Auch hier werden Tabs abgeschaltet sowie die Zeilenlänge auf 120 Zeichen hochgedreht.

Javadoc

In den Preferences werden die JavaDoc-Warnungen eingeschaltet:

Projektstruktur

Die Struktur eines Projekts (im Beispiel das Stateless-Beispiel mit EJB-Projekt, Webprojekt und ApplicationClient) sieht auf Festplatte so aus (Screenshot aus einer älteren Eclipse-Version und auf dem Stand von JavaEE5, grundlegend gilt das aber alles noch):

• Im Verzeichnis "StatelessClient\appClientModule" finden wir die Java-Quelldateien und im Unterverzeichnis "META-INF" die Deskriptoren. In "StatelessClient\build\classes" werden beim Build des Projekts die compilierten "class"-Dateien sowie benötigte Deployment-Deskriptoren abgelegt.
• Dito für "StatelessEJB\ejbModule": hier liegen die Java-Quelldateien. Im Unterverzeichnis könnten "META-INF" Deployment-Deskriptoren liegen. In "StatelessEJB\build\classes" laden beim Build die "class"-Dateien und die Deployment-Deskriptoren.
• Beim Webprojekt liegen die Java-Dateien im Unterverzeichnis "JavaSource", während die Deskriptoren und die JSP-Dateien im Verzeichnis "WebContent" liegen. In "StatelessWeb\build\classes" werden beim Build des Projekts die compilierten "class"-Dateien erstellt (hier werden allerdings keine Dateien aus WEB-INF kopiert).
• In "Stateless\EarContent" liegen die Deployment-Deskriptoren der EAR-Anwendung (falls vorhanden).

Debugging

Zum Debuggen dürfen wir den JBoss nicht "normal" starten sondern im Debug-Modus (Rechtsklick auf den Server, "Debug" wählen).


Im folgenden beziehe ich mich auf Klassen aus dem ersten Beispiel, "Stateless".
Wir setzen einen Breakpoint in der Methode doPost des GeometricModelServlet. Anschließend im Browser zu dieser URL navigieren:

JBoss-Knowhow

Verzeichnisstruktur

• "bin": enthält wichtige Scripte zum Serverstart und zur Administration. Beispiel:
  • "standalone.bat": startet einen Server im Standalone-Modus. Über diese Datei müssten wir JBoss immer starten, wenn Eclipse und das nicht abnehmen würde. Das Gegenstück zu dieser Datei ist "domain.bat": sie startet einen Server im Domain-Modus.
  • "jboss-cli.bat": startet das "Command Line Interface" von JBoss, also die konsolenbasierte Administrations-"oberfläche".
  • "appclient.bat": startet einen JavaEE-Application Client (jar-Datei innerhalb einer ear-Datei), siehe Stateless-Beispiel. Dazu wird ein Mini-JBoss-Umfeld gestartet, dessen Arbeitsbereich (Logdateien, Config, Temp-Verzeichnis) im Verzeichnis "%JBOSS_HOME%\appclient" liegt
  • "add-user.bat": kann Server-Benutzer anlegen - siehe weiter unten.
• "docs": enthält primär die XSD- und DTD-Dateien zu den von JBoss verwendeten Configdateien, darunter auch die XSDs des JavaEE-Umfelds.
• "standalone": enthält das Umfeld für einen JBoss im Standalone-Modus (für Details siehe nächster Abschnitt).
• "domain": enthält das Umfeld für einen JBoss im Domain-Modus. Für uns nicht relevant.
• "modules": enthält im Prinzip alle Jar-Dateien, die JBoss benötigt: jede Jar-Datei liegt in einer Verzeichnisstruktur, die ihrem Package entspricht. Jeder Package-Trenner wird zu einem Verzeichnis-Trenner. Ab JBoss 8 ist diese Verzeichnisstruktur erweitert worden: "modules\system\layers\base"

Standalone/Domain

• "configuration": Hier findet sich die Server-Konfiguration ("standalone.xml" ist der Default, die anderen "standalone-xx.xml"-Dateien biete andere Konfigurationsprofile und müssen explizit beim Serverstart angegeben werden, um genutzt zu werden.
  Die Dateien "mgmt-users.properties" und "application-users.properties" enthalten Benutzer, die mittels "%JBOSS_HOME%\add-user.bat" angelegt wurden.
• "data": enthält Laufzeitdaten des Servers, z.B. Transaktionen oder Timer
• "deployments": hier können im Standalone-Server Anwendungen abgelegt werden, die in den Server eingespielt werden sollen. Im Domain-Modus gibt es dieses Verzeichnis nicht. Mehr zum Deploy von Anwendungen weiter unten.
• "log": Protokolldateien des Servers. "boot.log" wird beim Serverstart geschrieben, "server.log" enthält genau die Ausgaben, die wir auch in der Konsole sehen.
• "tmp": enthält die temporären Dateien des Servers. Im Verzeichnis "vfs" (Virtual File System) finden sich in Unterverzeichnissen z.B. Dateien, die als Archiv ins "deployments"-Verzeichnis kopiert wurden und im "vfs"-Verzeichnis entpackt wurden. In "work" finden sich Daten des integrierten Webservers, siehe unten.

JBoss starten/stoppen

Command Line Interface (CLI)

• "quit" beendet die laufende Sitzung.
• "shutdown" stoppt den JBoss-Server

Web-Console

• Man ruft das Script %JBOSS_HOME%\bin\add-user.bat" auf
• Man wählt Option "a) Management User (mgmt-users.properties)"
• Im nächsten Schritt wird automatisch das Realm als "ManagementRealm" vorbelegt (JBoss 7.x und frühere WildFly 8.x-Versionen fragten hier nach)
• Jetzt gibt man einen Usernamen an. Hier kommen Warnungen, wenn der Username zu einfach ist. Für einen lokalen JBoss mag das aber OK sein.
• Im nächsten Schritt ist ein Passwort gefragt. Hier gibt es ziemlich strenge Validierungsregeln, die ein zu einfaches Passwort verbieten. Ohne Anspruch auf Vollständigkeit: das Passwort muss mind. 8 Zeichen lang sein. Es muss mindestens ein nicht-alphanumerisches Symbol enthalten.
  Wichtig: dieses Passwort irgendwo notieren - wir werden es später noch benötigen!
• Bei der Frage "What groups do you want this user to belong to?" (neu in WildFly 8.2) geben wir nichts an.
• Danach wird man gefragt, ob dieser Benutzer auch dazu verwendet werden soll, um von einem JBoss-Prozess aus eine Verbindung zu einem anderen JBoss-Prozess aufzubauen. Das können wir mit "no" verneinen.

In WildFly 19 gibt es einen vorkonfigurierten, aber deaktivierten User "admin" - siehe "mgmt-users.properties" (den Eintrag gibt es auch schon in früheren Versionen, aber die Meldung ist mir erst mit dieser Version aufgefallen). Gibt man hier den Usernamen "admin" an, kommt eine Abfrage "User 'admin' already exists and is disabled, would you like to...". Die Option "Enable the existing user" entfällt, da ich das Default-Passwort nicht kenne und der Kommentar in der Properties-Datei danach klingt, als wäre das kein "echtes" Passwort. Also wählt man Option a) und muss ihn dann genauso weiterverarbeiten wie oben beschrieben.

[standalone@localhost:9990 /] /subsystem=datasources/data-source=ExampleDS:read-attribute(name=connection-url)
{
    "outcome" => "success",
    "result" => "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
}

Deploy

[standalone@localhost:9999 /] deploy c:\temp\Stateless.ear

    <deployments>
        <deployment name="Stateless.ear" runtime-name="Stateless.ear">
            <content sha1="2a62e331dff5c46922429a1269da21f185f9d7b8"/>
        </deployment>
    </deployments>

[standalone@localhost:9999 /] undeploy Stateless.ear

Generierte JSP-Java-Klassen

JNDIView

Die JNDIView listet alle Einträge im Server-JNDI auf, darunter finden sich auch unsere eigenen Beans.

Webconsole
Über die Webconsole ist die "JNDIView" simpel zu erreichen (Anleitung ist auf dem Stand von WildFly 19): über den Karteireiter "Runtime" findet man links eine Liste der Server. Hier steht im Falle eines Standalone-Servers natürlich nur ein Eintrag. Diesen klickt man an. Danach öffnet sich in einer zweiten Spalte eine Liste der Subsysteme. Dort wählt man "JNDI" aus und klickt auf "View":


Auf der neuen Seite finden sich die JNDI-Einträge - im Beispiel für das Stateless-Beispiel:


CLI
Der benötigte Befehl ist:

[standalone@localhost:9999 /] /subsystem=naming:jndi-view

Das Ergebnis ist relativ unübersichtlich, enthält aber die gleichen Informationen wie die Webconsole:

JNDI-Namen

• Global: beginnt ein JNDI-Name mit "java:global", dann liegt dieser Eintrag global im Server vor und kann von allen Komponenten (die auf dem Server laufen oder auch von außen darauf zugreifen) abgerufen werden. Die Syntax ist:
  

  java:global[/application name]/module name/enterprise bean name[/interface name]

  Der optionale "application name" (und der "/" davor) ist nötig, wenn die deployte Anwendung Teil eines EAR ist. Ansonsten wird dieser Teil weggelassen.
  Der "interface name" ist ebenfalls optional: will man auf eine EJB über ein Local oder Remote Interface zugreifen, steckt hier der Name des Interfaces. Bei WildFly8 ist der per Default der volle Name des Interfaces ("Package.Interface"). Im Falle einer "no interface view" wird dieser Teil weggelassen (siehe Abschnitt im Stateful-Beispiel).
  
  
• Modul: beginnt ein JNDI-Name mit "java:module", dann liegt dieser Eintrag nur innerhalb des Moduls (z.B. ein EJB-JAR oder ein Web-Modul) vor und kann von allen Komponenten in diesem Modul abgerufen werden, aber nicht von Komponenten außerhalb. Die Syntax ist:
  

  java:module/enterprise bean name/[interface name]

  
  Bei einem Webmodul erlaubt dies nur Zugriff auf EJBs, die in der Webanwendung definiert sind. Ist das Webmodul Teil einer EAR-Datei, dann könnte man nicht auf EJBs zugreifen, die in einem separaten EJB-JAR liegen.
  
  
• Anwendung: beginnt ein JNDI-Name mit "java:app", dann liegt dieser Eintrag nur innerhalb der Anwendung (also einer EAR-Datei) vor und kann von allen Modulen in dieser Anwendung abgerufen werden, aber nicht von Komponenten außerhalb. Die Syntax ist:
  

  java:app[/module name]/enterprise bean name[/interface name]

  
  Hier kann eine Webmodul auf EJBs zugreifen, die in einer EJB-JAR liegen, sofern beide Module in einer EAR-Datei gebündelt sind.
  
  
• Komponente: jede Komponente kann außerdem einen privaten Namespace definieren. Ein Beispiel hierfür ist die Deklaration einer EJB-Referenz in "web.xml" oder "application-client.xml", die an einen JNDI-Eintrag gebunden ist. Was eine Komponente ist, ist unterschiedlich:
  Eine Webanwendung oder ein Application Client zählen als eine einzige Komponente, so dass alle im Deploymentdeskriptor deklarieren "java:comp"-Einträge allen Klassen im Modul zur Verfügung stehen. In den Deployment Deskriptoren sind die Elemente "ejb-ref" und "ejb-local-ref" globale Elemente.
  In einem EJB-JAR zählt jede EJB als Komponente und hat deshalb ihren eigenen "java:comp"-Namespace. Die Elemente "ejb-ref" und "ejb-local-ref" sind deshalb Kinder des "enterprise-beans/session"-Elements.
  Siehe http://stackoverflow.com/questions/7458114/what-is-the-relationship-between-javacomp-env-and-javaglobal
  
  In der Verwendung wird beim Lookup immer dieser JNDI Context vor den Namen gestellt: "java:comp/env/".
  In der Deklaration darf man "java:comp/env/" allerdings nicht angeben, da er implizit gilt.
  
  
• JBoss-Erweiterung: "java:jboss/exported": in diesem Namespace werden Remote Interfaces gebunden, auf die über Non-JavaEE-Anwendungen über das Verfahren "jboss-remote-naming" zugegriffen wird, siehe Zugriff auf Stateless Session Bean aus Java-Anwendung- Beispiel.
  
  
• JBoss-Erweiterung: "ejb:": in diesem Namespace werden Remote Interfaces gebunden, auf die über Non-JavaEE-Anwendungen über das Verfahren "JBoss EJB client" zugegriffen wird, siehe Zugriff auf Stateless Session Bean aus Java-Anwendung- Beispiel. Dieser Namespace gilt wohl nur in EJB-Clients.
  
  
• JBoss-Erweiterung: "java:jboss": diesen Namespace habe ich nur in der Server-Konfiguration vorgefunden: hier werden z.B. DataSources gebunden ("java:jboss/datasources/ExampleDS", für die Verwendung in der Anwendung siehe Kuchen-Beispiel)
  
  

	java:global/Stateless/StatelessEJB/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelLocal
	java:app/StatelessEJB/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelLocal
	java:module/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelLocal
	java:global/Stateless/StatelessEJB/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelRemote
	java:app/StatelessEJB/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelRemote
	java:module/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelRemote
	java:jboss/exported/Stateless/StatelessEJB/GeometricModelBean!de.fhw.komponentenarchitekturen.knauf.stateless.GeometricModelRemote

Logging

• JBoss Logging
• Apache Commons Logging - http://commons.apache.org/logging/
• Simple Logging Facade for Java (SLF4J) - http://www.slf4j.org/
• Apache log4j - http://logging.apache.org/log4j/1.2/
• Java SE Logging (java.util.logging)

        <subsystem xmlns="urn:jboss:domain:logging:1.2">
            <console-handler name="CONSOLE">
                <level name="INFO"/>
                <formatter>
                    <pattern-formatter pattern="%K{level}%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
                </formatter>
            </console-handler>
            <periodic-rotating-file-handler name="FILE" autoflush="true">
                <formatter>
                    <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
                </formatter>
                <file relative-to="jboss.server.log.dir" path="server.log"/>
                <suffix value=".yyyy-MM-dd"/>
                <append value="true"/>
            </periodic-rotating-file-handler>
			
            <file-handler name="StatelessFILE" autoflush="true">
                <formatter>
                    <pattern-formatter pattern="%d{HH:mm:ss,SSS} %-5p [%c] (%t) %s%E%n"/>
                </formatter>
                <file relative-to="jboss.server.log.dir" path="stateless.log"/>
                <append value="true"/>
            </file-handler>
			
            <logger category="com.arjuna">
                <level name="WARN"/>
            </logger>
            <logger category="org.apache.tomcat.util.modeler">
                <level name="WARN"/>
            </logger>
            <logger category="org.jboss.as.config">
                <level name="DEBUG"/>
            </logger>
            <logger category="sun.rmi">
                <level name="WARN"/>
            </logger>
            <logger category="jacorb">
                <level name="WARN"/>
            </logger>
            <logger category="jacorb.config">
                <level name="ERROR"/>
            </logger>
            <logger category="de.fhw.komponentenarchitekturen.knauf.stateless" use-parent-handlers="false">
                <level name="INFO"/>
                <handlers>
                    <handler name="StatelessFILE"/>
                </handlers>
            </logger>
            <root-logger>
                <level name="INFO"/>
                <handlers>
                    <handler name="CONSOLE"/>
                    <handler name="FILE"/>
                </handlers>
            </root-logger>
        </subsystem>

• Zuerst wird ein Handler deklariert. Dieser kümmert sich darum, was mit Logeinträgen passiert.
  Ein "console-handler" gibt sie auf der Konsole aus.
  Ein "periodic-rotating-file-handler" schreibt sie in eine Datei, deren Name sich nach einem bestimmten Muster aus dem aktuellen Datum aufbaut und entsprechend bei jedem Datumswechsel in eine neue Datei geschrieben wird. Genauer: die aktuellen Logausgaben landen immer in der gleichen Datei (hier: "server.log"), beim Datumswechsel wird diese Datei umbenannt in eine Datei mit Datumsstempel.
  Und der von mir benutzte "file-handler" ist die vereinfachte Variante: hier wird in eine Datei festen Namens geschrieben.
• Teil 2 der Konfiguration ist eine Filterung der Logeinträge, die im Log-Manager ankommen. Dies geschieht über das Element "logger". Das Element "category" gibt ein Package an: dieser Logger verarbeitet nur Logeinträge, die von Methoden dieses Packages geschrieben wurden. Ein Logger kann außerdem "handler" referenzieren: seine Logausgaben landen werden alle auf diesem Handler geschrieben. Dadurch kann loggt obiges Beispiel alle Einträge des Package "de.fhw.komponentenarchitekturen.knauf.stateless" in eine separate Logdatei.
  Außerdem laufen alle Logeinträge über den "root-logger". D.h. meine Stateless-Logeinträge würde auch auf die Serverkonsole und in "server.log" geschrieben. Will man diese verhindern, dann setzt man im "logger" das Element "use-parent-handlers" auf "false" - dadurch werden Logeinträge, die in den Filter dieses Logger fallen, nicht an den "root-logger" weitergereicht.