Tutorial: Einfache Session
Bean (Java_EJB_01) – XDoclet-Anweisungen
|
Dieses Tutorial
ist nur mehr sinnvoll, wenn Sie Kenntnisse für EJBs vor dem
EJB3-Standard erwerben wollen.
Mit
der Einführung des Standards EJB3 wird das Konfigurieren des
Deployment-Descriptors vereinfacht und die dafür notwendigen
XDoclet-Anweisungen innerhalb des Java-Codes sind nicht mehr
notwendig.
Das dem EJB3-Standard entsprechende Tutorial beginnt
mit dem Dokument Tutorial:
Einfache Session Bean, EJB3-Standard (Java_EJB_05) –
Einrichten des Projects.
Die
XDoclet-Anweisungen für das Generieren von Dateien sind bei
EJB3 nicht mehr notwendig; die notwendigen
Konfigurations-Anweisungen sind direkt im Java-Code
integriert.
Beispiele dazu finden Sie unter Tutorial:
Einfache Session Bean, EJB3-Standard (Java_EJB_05) –
Codieren.
Die
Kenntnisse für das Entwickeln von EJBs vor dem EJB3-Standard
sind nur dann sinnvoll wenn Sie älteren Code – mit den
darin enthaltenen Xdoclet-Anweisungen zum Generieren des
Deployment-Descriptors - für EJB adaptieren wollen.
|
Voraussetzungen
für das Verständnis dieses Dokuments:
Grundkenntnisse
in der Programmierung von Java (Klassen, Methoden, Schleifen) oder
anderer Objekt-Orientierter Programmiersprachen (z.B. C++,
Modula-2, Pascal).
Kenntnisse
im Umgang mit Eclipse; empfohlen ist das Durcharbeiten der
Einführungsbeispiele
für das Programmieren mit Java.
|
Ungefährer
Zeitbedarf zum Durcharbeiten dieses Dokuments:
Arbeitszeit:
Ca. .
|
Diesem
Dokument enthält die Anleitung für die Anweisungen zum
Generieren der XML-Datei, die das entwickelte EJB für den Java
Application Server beschreiben und die Java-Schnittstellen für
das entwickelte EJB generieren.
Zuerst
wird die Theorie des XDoclet erläutert.
Anschließend
werden die im Kommentar eingebetteten Anweisungen zum Generieren der
XML-Datei und der Java-Schnittstellen beschrieben.
Als letzter
Schritt werden die XDoclet-Parameter in den Project-Properties
definiert.
Dieses
Dokument erklärt ausführlich und mit Abbildungen wie die
Parameter für den XDoclet-Generator erfaßt werden.
Wenn
sie mit der Erfassung vertraut sind und nur eine Übersicht der
XDoclet-Parameter, -Properties und -Values suchen, finden Sie diese
im Dokument Session
Bean mit Datenbank-Zugriff (Java_EJB_03) – XDoclet-Anweisungen.
Inhaltsverzeichnis:
Vorigerer
Schritt: Codieren
Theorie
des XDoclet
Vorbedingungen
XDoclet
Konfiguration
* Generelle
XDoclet-Parameter für EJB
* Untergruppe
'fileset'-Parameter
* Untergruppe
'deploymentdescriptor'-Parameter
* Untergruppe
'jboss'-Parameter
* Untergruppen
'homeinterface'- und 'remoteinterface'-Parameter
* Untergruppe
'packagesubstitution'-Parameter
Speichern
der erfaßten Parameter und Kontrolle, ob die Datei erstellt
wurde
Ausführen des
XDoclet Generators und Prüfen des Ergebnisses
Weitere
Schritte und verwandte Dokumentation
Nächster
Schritt: Packen in JAR-Datei
Theorie
des XDoclet
XDoclet
ist ein Zusatz (Plugin) für Eclipse, eine populäre
Entwicklungsumgebung.
XDoclet
ist ein Kunstwort für das Verfahren, aus Kommandos in
Steuerdateien und in den Kommentaren (im Code der Java-Klassen der
EJBs) eingebetteten Anweisungen weitere Dateien zu generieren:
Die
Anweisungen innerhalb der Kommentare wurden bereits im vorigen
Schritt (Codieren) dokumentiert –
allerdings ohne Erläuterung deren Bedeutung.
In diesem
Schritt wird das Erstellen der Datei mit den Steueranweisungen für
XDoclet beschrieben.
Das Erstellen der Datei erfolgt mit
Unterstützung des JBoss-IDE Plugins für Eclipse. die
Vorbedingungen
▲ zum
Inhaltsverzeichnis
XDoclet
Konfiguration
|
Die
Konfiguration des XDoclet ist in den 'Properties' des jeweiligen
'Project' definiert.
Für das Ansehen und Ändern der
'Properties' wird mit der rechten Maustaste das Project
(Java_EJB_01) angeklickt und aus dem Kontext-Menu >Properties
ausgewählt.
|
|
|
Im
darauf hin erscheinenden Fenster (Properties für Java_EJB_01)
wird in der linken Spalte 'XDoclet Configuration' ausgewählt.
Um
die XDoclet-Generation zu erlauben, wird
[X] Enable XDoclet
markiert.
Anschließend
wird die Schaltfläche [ Add... ] angeklickt
um eine neue Konfiguration (Steuerdatei) für XDoclet zu
beginnen.
|
|
|
Im
darauf hin erscheinenden Fenster (Configuration Name) muß
ein frei gewählter Name für die XDoclet-Konfiguration
erfaßt werden.
Da
das XDoclet Dateien für das EJB erzeugen wird, wurde als
'Name' EJB
verwendet.
Durch
Klicken der Schaltfläche [ OK ] wird der
Name gültig und das Fenster geschlossen.
|
|
▲ zum
Inhaltsverzeichnis
Generelle
XDoclet-Parameter für EJB
|
Wählen
Sie im oberen Bereich das XDoclet aus.
Klicken
Sie dann mit der rechten Maustaste in den kleinen Bereich
darunter; das bewirkt das Erscheinen des abgebildeten
Kontext-Menus.
Wählen
Sie daraus 'Add Doclet...'.
|
|
|
Das
JBoss-IDE Plugin für Eclipse bietet eine Vielzahl von
vorbereiteten Prozeduren für verschiedenste Aufgaben.
Die
hier gestellte Aufgabe ist, ein XDoclet für das EJB zu
konfigurieren.
Deswegen
wird im angezeigten Fenster (Choose an entry) 'ejbdoclet'
ausgewählt.
Durch
Klicken der Schaltfläche [ OK ] wird die
Auswahl gültig und das Fenster geschlossen.
|
|
|
Für
die folgenden Eingaben wird empfohlen, das Fenster auf die volle
Bildschirmhöhe zu vergrößern.
Grund für
diese Empfehlung ist, daß damit der Bereich für die
'Properties' vergrößert wird und die einzelnen Werte
leichter ausgewählt werden können.
Weil
derzeit nur eine Art von XDoclet-Konfiguration 'ejbdoclet'
vorhanden ist, werden nur dessen 'Properties' im Bereich rechts
unten angezeigt.
Wären
mehrere XDoclet-Konfigurationen vorhanden, würden die
entsprechenden 'Properties' angezeigt wenn eine
XDoclet-Konfiguration ausgewählt wird.
|
|
|
Das
Erfassen der einzelne Werte geschieht immer auf die gleiche
Weise.
Deswegen wird nur das Vorgehen für die 'destDir'
mit Abbildungen beschrieben.
Das
Erfassen der weiteren Werte wird dann nur mehr in Tabellenform
dokumentiert.
|
|
|
Durch
einen Doppelklick mit der linken Maustaste auf die Zeile 'destDir'
öffnet sich ein Fenster für die Eingabe des Wertes. Der
Wert (src/java
als Standardwert für alle EJB die entsprechend dieses
Dokumentation erstellt werden) wird im Feld 'Value' eingegeben und
das Fenster durck Anklicken der Schaltfläche [ OK ]
wieder geschlossen.
Im
rechten unteren Bereich ist anschließend der erfaßte
Wert (src/java) für
die Property ('destDir') zu sehen.
Erklärung
des Wertes:
Damit wird das Verzeichnis definiert, in dem
XDoclet die generierten Dateien für die Java-Interfaces
speichert.
Die
Bezeichnung mag etwas verwirrend sein -
'destDir' (destination
directory) ist das Verzeichnis aus der Sicht von XDoclet; für
den Java-Compiler ist es dann die 'Source'-Directory.
|
|
|
Property
|
Value
|
Zweck
|
|
destDir
|
src/java
|
Ziel-Verzeichnis
für XDoclet.
In diesem Verzeichnis speichert XDoclet die
erzeugten Dateien mit dem Code für die Java-Interfaces.
|
|
ejbSpec
|
2.0
|
Anweisung,
daß die erzeugten Dateien der EJB-Spezifikation entsprechen.
|
▲ zum
Inhaltsverzeichnis
Untergruppe
'fileset'-Parameter
Mit
diesen Parametern wird festgelegt, welche manuell erstellten Dateien
XDoclet durchsuchen soll.
Nur die in diesen Parametern
festgelegten Verzeichnisse und Dateien werden geprüft ob
eingebettete XDoclet-Anweisungen vorhanden sind.
|
Wählen
Sie im unteren Bereich 'ejbdoclet' aus und Klicken Sie mit der
rechten Maustaste darauf.
Im
anschließend erscheinenden Kontext-Menu wählen Sie
'Add...'.
|
|
|
Das
JBoss-IDE Plugin für Eclipse bietet eine Vielzahl von
vorbereiteten Prozeduren für verschiedenste Aufgaben.
Die
hier gestellte Aufgabe ist, ein XDoclet für das EJB zu
konfigurieren.
Im
angezeigten Fenster (Choose an entry) wird 'fileset' ausgewählt.
Durch
Klicken der Schaltfläche [ OK ] wird der
Auswahl gültig und das Fenster geschlossen.
|
|
|
Nach
dem Schließen des Auswahlfensters wird die Untergruppe
'fileset' angezeigt.
Sollte die Untergruppe nicht angezeigt
werden, klicken Sie bitte auf das kleine Dreieck links neben
'ejbdoclet'.
Die
Werte der einzelnen Properties werden auf die selbe Weise erfaßt
wie bereits unter Generelle
XDoclet-Parameter für EJB beschrieben.
|
|
|
Property
|
Value
|
Zweck
|
|
dir
|
src/java
|
Verzeichnis,
in dem XDoclet die Dateien nach den speziellen Xdoclet-Anweisungen
durchsucht.
|
|
excludes
|
Diese
Auswahl wird deaktiviert
|
Diese
'Property' erlaubt, Dateien, deren Namen dem definierten Muster
entspricht, nicht zu durchsuchen.
Nachdem die Auswahl der
Dateien über 'includes' gesteuert wird, wird diese Property
nicht verwendet.
|
|
includes
|
**/*Bean.java
|
Muster
für den Dateinamen der Dateien, die XDoclet durchsuchen
soll.
**/
bedeutet, daß auch Unterverzeichnisse durchsucht
werden.
*Bean.java
bedeutet, daß alle Dateien, deren Namen mit Bean.java
endet, durchsucht werden.
|
|
Wenn
alle 'Properties' erfaßt sind, sind die gezeigten Werte zu
sehen.
|
|
▲ zum
Inhaltsverzeichnis
Untergruppe
'deploymentdescriptor'-Parameter
Im
deployment-descriptor sind die Informationen über das EJB
enthalten die vom Java-Application-Server benötigt werden.
Es
ist eine Normierung, daß die deployment-Informationen in einer
Datei mit Namen 'ejb-jar.xml' im Unterverzeichnis 'META-INF'
enthalten sind.
|
Noch
einmal eine Wiederholung, wie eine Untergruppe angelegt wird.
Wählen
Sie im unteren Bereich 'ejbdoclet' aus und Klicken Sie mit der
rechten Maustaste darauf.
Im
anschließend erscheinenden Kontext-Menu wählen Sie
'Add...'.
Im
anschließend angezeigten Fenster (Choose an entry / ohne
Abbildung) wird 'deploymentdescriptor' ausgewählt.
Durch
Klicken der Schaltfläche [ OK ] wird die
Auswahl gültig und das Fenster geschlossen.
Nach
dem Schließen des Auswahlfensters werden die bestehenden
Untergruppen angezeigt (ohne Abbildung).
Sollten die
Untergruppen nicht angezeigt werden, klicken Sie bitte auf das
kleine Dreieck links neben 'ejbdoclet'.
|
|
|
Eine
detaillierte Beschreibung, wie die Parameter einer Untergruppe
erfaß werden, ist unter Untergruppe
'fileset'-Parameter zu
finden.
Die
Werte der einzelnen Properties werden auf die selbe Weise erfaßt
wie bereits unter Generelle
XDoclet-Parameter für EJB beschrieben.
|
|
Property
|
Value
|
Zweck
|
|
destDir
|
gen/META-INF
|
Dieser
Parameter weist XDoclet an, die Datei 'ejb-jar.xml' im Verzeichnis
'gen/META-INF' zu speichern. Von dort wird sie zu einem späteren
Zeitpunkt in die .JAR-Datei (für dem Java-Application-Server)
gepackt.
|
|
Wenn
alle 'Properties' erfaßt sind, sind die gezeigten Werte zu
sehen.
|
|
▲ zum
Inhaltsverzeichnis
Untergruppe
'jboss'-Parameter
Die
Parameter in dieser Untergruppe enthalten spezielle Informationen für
eine Fein-Abstimmung auf den JBoss
Java-Application-Server (JAS).
Für das einfache Beispiel in
diesem Tutorial werden die speziellen Möglichkeiten der
Parameterisierung für einen speziellen JAS nicht genützt.
Wenn
Sie einen anderen JAS als JBoss nutzen, können Sie die
generierte Datei ('jboss.xml') mit großer Wahrscheinlichkeit –
nach einem Umbenennen des Dateinamens – auch für Ihren
ausgewählten JAS verwenden.
Für
das Anlagen der Untergruppe und die Erfassung der Parameter sehen Sie
bitte unter Untergruppe
'fileset'-Parameter nach.
|
Property
|
Value
|
Zweck
|
|
Version
|
3.0
|
Dieser
Parameter weist XDoclet an, eine Datei mit Namen 'jboss.xml' zu
generieren in der auf JBoss Version 3.0 (oder neuere Versionen)
abgestimmte spezielle Anweisungen enthalten sind.
Wenn
Sie alternativ oder zusätzlich Parameter für andere
Java-Application-Server erfassen, werden ebenfalls Dateien mit
abgestimmten Namen und Anweisungen für die jeweiligen JAS
generiert.
|
|
destDir
|
gen/META-INF
|
Dieser
Parameter weist XDoclet an, die Datei 'jboss.xml' im Verzeichnis
'gen/META-INF' zu speichern. Von dort wird sie zu einem späteren
Zeitpunkt in die .JAR-Datei (für dem Java-Application-Server)
gepackt.
|
|
Wenn
alle 'Properties' erfaßt sind, sind die gezeigten Werte zu
sehen.
Der Parameter 'Version' ist zu Beginn der Liste und auf
der Abbildung nicht mehr sichtbar.
|
|
▲ zum
Inhaltsverzeichnis
Untergruppen
'homeinterface'- und 'remoteinterface'-Parameter
Diese
Parameter weisen XDoclet an, aus den Klassen mit der codierten
Geschäftslogik (siehe asdf) zusätzliche 'Interfaces' zu
generieren.
Diese Interfaces werden später auch Teil der EJB
und enthalten Beschreibungen für die Klassen mit der
Geschäftslogik. Damit können 'Client'-Programme das EJB
aufrufen und die Geschäftslogik ausführen.
Für
das Anlagen der Untergruppe und die Erfassung der Parameter sehen Sie
bitte unter Untergruppe
'fileset'-Parameter nach.
Für
diese Untergruppe sind keine einzelnen Parameter zu erfassen.
▲ zum
Inhaltsverzeichnis
Untergruppe
'packagesubstitution'-Parameter
Im
vorigen Schritt wurde XDoclet angewiesen, Java-'Interfaces' zu
generieren.
Ohne weitere Spezifikation würden die generierten
Java-'Interfaces' im Java-'Package' 'bean' bleiben.
Damit die
Interfaces leichter in Client-Programme integriert werden können,
ist es aber zweckmäßig, sie in einem eigenen Package (mit
Namensteil 'interface') zusammenzufassen.
Die Anweisung dazu
erfolgt mit den Parametern in dieser Untergruppe.
Wenn
Sie den Sinn der Aktion bis jetzt noch nicht verstanden haben, fahren
Sie bitte trotzdem fort – das Verwenden des Packages mit den
java-'Interface' wird in einem späteren Tutorial gezeigt.
Für
das Anlagen der Untergruppe und die Erfassung der Parameter sehen Sie
bitte unter Untergruppe
'fileset'-Parameter nach.
|
Property
|
Value
|
Zweck
|
|
packages
|
bean
|
Dieser
Parameter weist XDoclet an, eine Datei mit Namen 'jboss.xml' zu
generieren in der auf JBoss Version 3.0 (oder neuere Versionen)
abgestimmte spezielle Anweisungen enthalten sind.
Wenn
Sie alternativ oder zusätzlich Parameter für andere
Java-Application-Server erfassen, werden ebenfalls Dateien mit
abgestimmten Namen und Anweisungen für die jeweiligen JAS
generiert.
|
|
substituteWith
|
interfaces
|
Dieser
Parameter weist XDoclet an, die Datei 'jboss.xml' im Verzeichnis
'gen/META-INF' zu speichern. Von dort wird sie zu einem späteren
Zeitpunkt in die .JAR-Datei (für dem Java-Application-Server)
gepackt.
|
|
Wenn
alle 'Properties' erfaßt sind, sind die gezeigten Werte zu
sehen.
|
|
▲ zum
Inhaltsverzeichnis
Speichern
der erfaßten Parameter und Kontrolle, ob die Datei erstellt
wurde
|
Die
in den vorigen Schritten erfaßten Parameter werden durch
Anklicken der Schaltfläche [ OK ]
gesichert.
Gleichzeitig wird eine Input-Datei für den
XDoclet-Generator erstellt.
Das
Erstellen der Input-Datei dauert einige Sekunden und wird durch
ein Fenster mit Fortschrittsbalken (nicht abgebildet) angezeigt.
|
|
|
Die
generierte Input-Datei für Xdoclet hat den Namen
'xdoclet-build.xml' und ist in der Datei-Struktur ('Package
Explorer') des 'Project's zu sehen.
|
|
▲ zum
Inhaltsverzeichnis
Ausführen
des XDoclet Generators und Prüfen des Ergebnisses
|
Das
Ausführen des XDoclet-Generators wird durch Anklicken des
'Project's mit der rechten Maustaste und dann Auswählen von
Run XDoclet gestartet.
|
|
|
Abhängig
von der Leistung des Computers braucht der XDoclet-Generator
einige Sekunden für seine Arbeit.
Der
Fortschritt und der Abschluß der Generierung kann im
'Console' Bereich von Eclipse verfolgt werden.
|
|
|
Als
weiter Indikation der erfolgreichen Ausführung ist ein neues
'Package' (js_ejb01.ejb.interfaces) mit zwei Dateien zu sehen.
|
|
▲ zum
Inhaltsverzeichnis
Weitere
Schritte und verwandte Dokumentation
▲ zum
Inhaltsverzeichnis