Tutorial: Client-Programm für Einfache Session Bean, EJB3-Standard (Java_EJB_06)

Diesem Dokument enthält die Anleitung für die Programmierung eines einfachen Client-Programms das die Methode des in den Dokumenten beginnend mit Tutorial: Einfache Session Bean, EJB3-Standard (Java_EJB_05) – Einrichten des Projects entwickelten EJB (Enterprise Java Bean) benutzt.

Inhaltsverzeichnis:

Installationanleitung für die frühere Version (vor EJB3-Standard) 

Vorbemerkung 
Vorbedingungen 
Project eröffnen und einrichten 
* Project eröffnen 
* Verzeichnisse für Quell-Code und kompilierte Java-Klassen festlegen 
* Standard-Source-Verzeichnis prüfen und bei Bedarf korrigieren 
* Einbindung der Libraries (Programm-Bibliotheken) in den Java Build Path 
Java-Klasse anlegen 
Eingabe des Länder-Codes abfragen; Code testen 
Datei jndi.properties mit den Parametern für die Verbindung zum JAS anlegen 
Verbindungsdaten zum JAS codieren, Methode des EJB aufrufen und Ergebnis anzeigen; Code testen 

Hinweise zur Fehlersuche 

Gesamter Code am Ende des Schrittes 
Datei ShowTimeDateClient.java 
Datei jndi.properties 

Bewusste Vereinfachungen in diesem Tutorial-Schritt – im Vergleich zu professioneller Entwicklung 

Weitere Schritte und verwandte Dokumentation 

Installationsanleitung für die frühere Version (vor EJB3-Standard)

Wenn Sie vor der Aufgabe stehen, Java vor Version 1.5 (auch als Java 5 bezeichnet) verwenden zu müssen, Client-Programme für den Zugriff auf EJBs neu schreiben oder adaptieren müssen und die passende Anleitung dafür suchen - dann finden Sie diese im
Tutorial: Client-Programm für Einfache Session Bean (Java_EJB_02).

▲ zum Inhaltsverzeichnis

Dank für Vorarbeiten

Eine exzellente Einführung in die generelle Programmierung von EJB war der JBoss-IDE 1.3.0 Tutorial Guide von Hans Dockter und Laurent Etiemble.
Beispiele, die über das Tutorial in diesem Dokument hinausgehen, schrieb Mirza Jahic in Working with JBoss and Eclipse.

Speziell auf EJB 3 adaptiert ist das First EJB 3 Ant Tutorial von Sebastian Hennebrueder.

▲ zum Inhaltsverzeichnis

Vorbemerkung

Viele der in diesem Tutorial auszuführenden Abschnitte (z.B. Eröffnen des Project) sind gleich oder sehr ähnlich zu Abschnitten, die bereits im Tutorial für die Entwicklung der Einfachen Session Bean beschrieben wurden.
Um diese – bei jedem Project wiederkehrenden - Tätigkeiten zu üben, wird in diesem Tutorial nicht immer jede Tätigkeit im Detail beschrieben und eine Abbildung gezeigt.
Statt dessen wird auf die entsprechende Beschreibung in einem Tutorial, das als Vorbedingung durchzuarbeiten war, verwiesen.

Vorbedingungen:

• Session Bean entwickelt, in eine EAR-Datei gepackt und wie in Einfache Session Bean, EJB3-Standard - Packen in EAR-Datei und Ändern des JNDI-Namens > 'Deploy' der EAR-Datei im Java Application Server (JAS) und Test beschrieben an einen JAS (Java Application Server) übergeben.
  Wenn Sie das Tutorial bei Einfache Session Bean, EJB3-Standard - Packen der Dateien in Java-Archive (JAR) und 'deploy' > JAR-Datei an den JAS übergeben ('deploy') unterbrochen haben, beachten Sie bitte den Hinweis auf den geänderten JNDI-Namen im Source-Code des Client-Programms.
  Hinweis bei Verwendung von Glassfish:
  In der Version 2.1.1 kann das Client-Programm das EJB in der JAR-Datei nicht aufrufen; bei Glassfish Version 2.1.1 muss das EJB in eine EAR-Datei gepackt werden.

• JAR-Datei mit den Schnittstellen für die Client-Programme (wie in Einfache Session Bean, EJB3-Standard - Packen der Dateien in Java-Archive (JAR) und 'deploy' > JAR-Datei für Client-Programme erstellen beschrieben) vorhanden.

• Und natürlich alle Vorbedingungen für die beiden oberen Vorbedingungen ;-) .

▲ zum Inhaltsverzeichnis

Project eröffnen und Einrichten

Kriterien für das Gruppieren von Projects in einen Workspace wurden in Tutorial: Hello World (Java_Intro_01) > Eclipse Workspace und Project eröffnen diskutiert.
Dort ist auch eine Beschreibung mit Screenshots enthalten wie ein Workspace eingerichtet wird – diese Anleitung wird in diesem Dokument nicht mehr wiederholt.

▲ zum Inhaltsverzeichnis

Project eröffnen

▲ zum Inhaltsverzeichnis

Verzeichnisse für Quell-Code und kompilierte Java-Klassen festlegen

▲ zum Inhaltsverzeichnis

Standard-Source-Verzeichnis prüfen und bei Bedarf korrigieren

Die Meldung im vorigen Absatz ließe darauf schließen, daß das Standard-Source-Verzeichnis (Java_EJB_06/src) als Source-Verzeichnis gelöscht ist.
Bei einer meiner früher installierten Versionen von Eclipse (Version: 3.3.1.1., Build id: M20071023-1652) war das wider Erwarten nicht der Fall.

Überprüfen Sie bitte zur Sicherheit die Definition der Source-Verzeichnisse bei Ihrer Installation analog der Beschreibung unter Einfache Session Bean, EJB3-Standard – Einrichten des Projects > Standard-Source-Verzeichnis prüfen und bei Bedarf korrigieren.
Wenn der 'Fehler' auch bei Ihnen aufgetreten ist, führen Sie bitte die dort beschriebene Korrektur durch.

▲ zum Inhaltsverzeichnis

Einbindung der Libraries (Programm-Bibliotheken) in den Java Build Path

In diesem Project wird der Code (Klassen) in Programmteilen, die nicht innerhalb des Projects oder der Eclipse-Workspace vorhanden sind, eingebunden.

Eine detaillierte Anleitung, wie Bibliotheken eingebunden werden ist unter Einfache Session Bean, EJB3-Standard – Einbindung der Libraries (Programm Bibliotheken) in den Java Build Path beschrieben. Die dort aufgelisteten Dateien werden für ein Client-Programm aber nicht benötigt.

Wenn Sie vorläufig keine JAR-Datei mit den benötigten Klassen zur Verfügung haben (weil noch kein JAS installiert ist), können Sie eine der folgenden Dateien herunterladen:
* Für IBM WAS-CE (Version 2.1.1.3): geronimo-ejb_3.0_spec-1.0.1.jar, openejb-client-3.0.1.jar 
* Für Glassfish (Version 2.1): appserv-rt.jar, javaee.jar 
* Für JBoss (Version 5.1.0): jbossall-client.jar 

▲ zum Inhaltsverzeichnis

Java-Klasse anlegen

In diesem Abschnitt wird die Klasse für das Client-Programm Zug um Zug codiert und zwischenzeitlich wird getestet um Fehler frühzeitig erkennen zu können.

In den nächsten Abschnitten wird der Programm-Code Schritt für Schritt entwickelt und nach jedem Schritt wird getestet, ob die Verbindung zum JAS und der Aufruf der Methode des EJB wie erwartet funktioniert.

▲ zum Inhaltsverzeichnis

Eingabe des Länder-Codes abfragen

Dieser Teil des Codes hat noch keinen Bezug zur Programmierung mit EJB.
Hier wird nur in einer Schleife auf die Eingabe des Länder-Codes gewartet.

Code in Normal-Schrift wurde beim Anlegen der Klasse generiert; Code in Fettschrift ist der individuell erstellte Code.

package js_ejb06.client;
/*
 * Package mit den Länder-Codes und -Langnamen. */
import js_ejb05.staticvalues.CountryConstants;
/*
 * Package mit verschiedenen Methoden für Ein- und Ausgabe. */
import java.io.*;

public class ShowTimeDateClient {

    public ShowTimeDateClient() {
        // TODO Auto-generated method stub
      super();
    }

    /**
     * @param args
    */
    public static void main(String[] args) {
        // TODO Auto-generated method stub
/*
 * Anzahl der Länder-Codes im Array;
 * Index für das Ansprechen der Länder-Codes und Langnamen im Array. */
        int CountryArraySize = CountryConstants.Country.length;
        int CountryArrayIndex = 0;
/*
 * Bauen des Strings mit der Konsol-Ausgabe
 * (Erklärung was als Konsol-Eingabe erwartet wird). */
        String strKonsolErklaerung = "Bitte geben Sie den möglichen Länder-Code [";
        for (CountryArrayIndex = 0; CountryArrayIndex < CountryArraySize; CountryArrayIndex++) {
            strKonsolErklaerung +=
                CountryConstants.Country[CountryArrayIndex][0].trim().toUpperCase();
            if (CountryArrayIndex < (CountryArraySize - 1)) strKonsolErklaerung += ", ";
        }
        strKonsolErklaerung += "] ein oder lassen sie das Feld leer um das Programm zu beenden: ";
/*
 * Variablen für die Eingabe auf der Konsole. */
        String strKonsolAntwort = "";
        byte byteKonsolBuffer[] = new byte[80];
        int intKonsolBufferLaenge;
/*
 * Schleife für das Abfragen der Eingabe auf der Konsole und Aufrufen des EJB. */
        for (;;) {
/*
 * Anzeigen der Erklärung auf der Konsole. */
            System.out.print(strKonsolErklaerung);
/*   */
            try {
/*
 * Antwort (Eingabe auf der Konsole) einlesen. */
                intKonsolBufferLaenge = System.in.read(byteKonsolBuffer, 0, 80);
                strKonsolAntwort = new String(byteKonsolBuffer, 0, intKonsolBufferLaenge);
/*
 * Umwandeln in Grossbuchstaben und führende und nachfolgende Leerzeichen entfernen. */
                strKonsolAntwort = strKonsolAntwort.toUpperCase().trim();
            }
            catch (IOException e) {
/* Unerwarteter Fehler bei der Konsol-Eingabe; Fehlermeldung auf die Konsole ausgeben. */
                e.printStackTrace();
            }
/*
 * Prüfen ob 'leere' Antwort und in diesem Fall Programm beenden. */
            if (strKonsolAntwort.length() <= 0) {
              System.out.println("Programm beendet");
              System.exit(0);
            }
/*
 * Eingabe als Rückmeldung wieder ausgeben. */
            System.out.println("Eingegeben: " + strKonsolAntwort);
        }
    }
}

Dieser Teil des Codes kann jetzt getestet werden.

Mögliche Fehler:
Abgesehen von Tippfehlern kann die importierte Interface js_ejb05.staticvalues.CountryConstants nicht vorhanden sein.
Prüfen Sie bitte, ob im Abschnitt Einbindung der Libraries (Programm-Bibliotheken) in den Java Build Path die Datei 'Java_EJB_05-client.jar' aufgenommen wurde.

▲ zum Inhaltsverzeichnis

Datei jndi.properties mit den Parametern für die Verbindung zum JAS anlegen

Mit dem EJB3-Standard ist es möglich, die Parameter für die Verbindung zum JAS (Java Application Server) in einer Datei außerhalb des Programm-Codes anzulegen.
Damit wird bei einer Änderung des JAS die Anpassung von Heavyweight-Clients wesentlich erleichtert.

Die Datei wird von den sie einlesenden Java-Klassen im 'root'-Verzeichnis – das ist das Verzeichnis in dem die Java-Packages als Unterverzeichnis sind – erwartet.

Die folgenden Werte für die Parameter sind auf den JBoss JAS, der auf dem gleichen Computer wie Eclipse läuft, abgestimmt.

Wenn Sie einen anderen JAS verwenden ist der Name der verwendeten Java-Klassen und eventuell auch der Name der Datei ('jndi.properties') anders als hier beschrieben.
Beispiele für Glassfish (von Sun) und WAS-CE (von IBM) finden Sie im Abschnitt Gesamter Code am Ende des Schrittes > Datei jndi.properties.
Wenn Sie WAS-CE verwenden und dieser nicht auf dem gleichen Computer, den Sie für die Entwicklung mit Eclipse verwenden, läuft adaptieren Sie bitte die TCP/IP-Adresse.

java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
java.naming.provider.url=127.0.0.1:1099

Eine kurze Erklärung der einzelnen Teile der 'Eigenschaften':

• java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces

  Diese Klassen enthalten den Algorithmus für den Aufbau der Verbindung vom Client-Programm zum JBoss JAS.
  Jeder kommerzielle JAS verwendet einen eigenen Verschlüsselungs-Algorithmus für die Übertragung der Daten zwischen Client-Programm und JAS; bei JBoss sind die angegebenen Klassen für den Aufbau und die Verschlüsselung zuständig.

• java.naming.provider.url=127.0.0.1:1099

  Damit wird dem Client-Programm mitgeteilt unter welcher TCP/IP-Adresse und welchem Port der JAS 'auf Anfragen horcht'.
  
  Um nicht durch eine Firewall oder andere Sicherheitsmechanismen behindert zu werden – und damit unnötige Zeit in Fehlersuche zu investieren – wird empfohlen, den JAS (z.B. JBoss) auf dem gleichen Computer laufen zu lassen wie das entwickelte Programm.
Die TCP/IP-Adresse im obigen Beispiel (127.0.0.1) bezieht sich auf den lokalen Computer.

▲ zum Inhaltsverzeichnis

Verbindungsdaten zum JAS codieren, Methode des EJB aufrufen und Ergebnis anzeigen

Die Erklärungen der jeweiligen Kommandos finden Sie im Kommentar innerhalb des Codes.
Wenn Sie die zusätzlichen Zeilen nicht selbst eintippen wollen können Sie den gesamten Code für diese Klasse (ShowTimeDateClient.java) kopieren; folgen Sie dazu dem markierten Link.

package js_ejb06.client;
/*
......
......
import java.io.*;
/*
 * Package mit verschiedenen Klassen für die Verbindung zum Java Application Server (JAS). */
import javax.naming.*;
/*
 * (Java-)Interface mit den Länder-Codes und -Langnamen. */
import js_ejb05.staticvalues.CountryConstants;
/*
 * Interface zur EJB die auf dem JAS läuft. */
import js_ejb05.ejb.interfaces.remote.ShowTimeDateBeanRemote;

public class ShowTimeDateClient {
......
......
/*
 * Eingabe als Rückmeldung wieder ausgeben. */
            System.out.println("Eingegeben: " + strKonsolAntwort);
/*
 * Beginn des Codes für das Nutzen der Methoden des EJB. */
            try {
/*
 * Objekt der Klasse 'InitialContext' erstellen.
 * Dabei werden die Werte für den Aufbau der Verbindung zum EJB ('Properties', deutsch: Eigenschaften)
 * aus einer Datei eingelesen.
 * Der Name der Datei mit den 'Properties' ist in der Klasse 'InitialContext', die mit dem Java-package
 * 'javax.naming' importiert wird, enthalten – üblicherweise heisst die Datei 'jndi.properties' und
 * wird von den im Beispiel verwendeten JAS (Glassfish und JBoss) unter diesem Namen erwartet.
 * Andere JAS können möglicherweise andere Dateinamen erwarten.
 * 
 * Für die Beispiele in diesem Tutorial wird JBoss verwendet – aber der Code hier ist völlig neutral
 * und für jeden JAS passend.
 * 
 * Das package 'java.naming' ist in der JAR-Datei, die zum verwendeten JAS (Java-Application-Server)
 * gehört, enthalten – für JBoss ist das die Datei 'jbossall-client.jar'.
 * Die Festlegung, dass die Werte für die Verbindung in der Datei 'jndi.properties' enthalten sind,
 * bei JBoss in folgender Kette festgelegt:
 * Bibliothek: jbossall-client.jar (JBoss-spezifisch) >
 * package: javax.naming (Java-spezifisch, für alle JAS gültig – aber vom Hersteller des JAS codiert) >
 * Klasse: InitialContext (Java-spezifisch, für alle JAS gültig – aber vom Hersteller des JAS codiert)
 *  */
                Context initialContext = new InitialContext();
/*
 * Construction der Interface, über die ein Objekt des EJB am JAS konstruiert wird und
 * später dessen Methoden aufgerufen werden.
 * Der JNDI-Name ('ejb/ShowTimeDateBeanJNDI') ist beim EJB festgelegt. */
                ShowTimeDateBeanRemote remoteShowTimeDateBean;
                remoteShowTimeDateBean = (ShowTimeDateBeanRemote)
                    initialContext.lookup("mapped_ShowTimeDateBeanJNDI");
/* Der JNDI-Name in der obigen Code-Zeile setzt voraus, dass die EAR-Datei 'deployed' wurde.
 * Wenn Sie die JAR-Datei deployed haben, setzen Sie die obere Zeile 'unter Kommentar'
 * und entfernen den Kommentar vor der unteren Zeile. */
//                    initialContext.lookup("ejb/ShowTimeDateBeanJNDI");
/*
 * Ausführen der Methode und Ausgabe des Ergebnisses auf der Konsole. */
                String[] result = remoteShowTimeDateBean.getTimeDateString(strKonsolAntwort);
                System.out.println("Result[0]: " + result[0]);
                System.out.println("Result[1]: " + result[1]);
            }
            catch (NamingException e) {
/* Unerwarteter Fehler beim Erstellen des InitialContext oder beim Ausführen der Methoden des EJB;
 * Fehlermeldung auf die Konsole ausgeben. */
                System.out.println("NamingException");
                e.printStackTrace();
            }
        }
    }
}

Der gesamte Code kann jetzt getestet werden.

Bemerkung:
Damit der Code getestet werden kann, muss das EJB an den JAS übergeben ('deployed') sein; die Anleitung dazu finden Sie unter Tutorial: Einfache Session Bean, EJB3-Standard (Java_EJB_05) – Packen der Dateien in Java-Archive (JAR) und 'deploy' > JAR-Datei an den JAS übergeben ('deploy').
Um nicht durch Firewalls oder andere Sicherheitsmechanismen behindert zu werden – und damit unnötige Zeit in Fehlersuche zu investieren – wird empfohlen, den JAS (z.B. JBoss) auf dem gleichen Computer laufen zu lassen wie das entwickelte Programm.
Die TCP/IP-Adresse (127.0.0.1; festgelegt in der Datei 'jndi.properties') bezieht sich auf den lokalen Computer und erlaubt die Verbindung zum EJB innerhalb einer möglichen Firewall.

Weiters sind als JAR-Dateien für die Verbindung zum JAS jene JAR-Dateien, die mit dem JAS geliefert wurden, zu verwenden.
Im Abschnitt Einbundung der Libraries (Programm-Bibliotheken) in den Java Build Path wurden eventuell nicht zum JAS passende JAR-Dateien eingebunden damit der Code vorerst compiliert werden kann ohne das ein Fehler auftritt weil benötigte Packages fehlen.
Damit der Test fehlerfrei ausgeführt werden kann, müssen dafür die zur jeweiligen Version des JAS passenden JAR-Dateien eingebunden werden.

Aus dem Eclipse-Menu wird Run >Run ausgewählt.

▲ zum Inhaltsverzeichnis

Hinweise zur Fehlersuche

Bedingt durch die Trennung in Server-seitigen Code (EJB) und Code im Client-Programm können verschiedene Fehler nicht wie Syntax-Fehler sofort beim Tippen des Codes identifiziert werden.
Ein – vielleicht leicht zu übersehender – Tippfehler führt dazu, dass das EJB nicht korrekt im JAS 'deployed' wird oder das Client-Programm keine Verbindung zum EJB aufnehmen kann.
Zusätzlich werden Parameter für die Verbindung in einer externen Datei ('jndi.properties') bereitgestellt. Ein einziger Tippfehler in dieser Datei führt ebenfalls dazu, dass die benötigte Klasse für die Verbindung nicht geladen werden kann oder versucht wird, eine Verbindung zu einer unpassenden TCP/IP-Adresse aufzunehmen.

Als LeserIn dieses Tutorials haben Sie vermutlich überhaupt keine Erfahrung mit der Eingrenzung eines Fehlers – deswegen folgen leicht auszuführende Schritte zur Eingrenzung des Fehlers.

'Fertige' JAR- und EAR-Datei für den JAS

Wenn Sie einen Fehler in der Klasse für das EJB vermuten können Sie mit JBoss (Version 5.1.0) und Glassfish (Version 2.1.1) getestete Archiv-Dateien herunter laden und für einen Test auf korrekte Funktion des Client-Programms (dieses Tutorials) verwenden.
Die für das EJB passenden Schnittstellen für das (in diesem Dokument vorgestellte) Client-Programm finden Sie in der Datei Java_EJB_05-client.jar.

• Java_EJB_05.jar
Wenn Sie dieses EJB-JAR (Java-ARchive) verwenden beachten Sie bitte, dass der JNDI-Name im Client-Programm angepasst werden muss.
Tauschen Sie die Kommentare zwischen den einzelnen Zeilen:
                remoteShowTimeDateBean = (ShowTimeDateBeanRemote)
//                    initialContext.lookup("mapped_ShowTimeDateBeanJNDI");
/* Der JNDI-Name in der obigen Code-Zeile setzt voraus, dass die EAR-Datei 'deployed' wurde.
 * Wenn Sie die JAR-Datei deployed haben, setzen Sie die obere Zeile 'unter Kommentar'
 * und entfernen den Kommentar vor der unteren Zeile. */
                    initialContext.lookup("ejb/ShowTimeDateBeanJNDI");

• Java_EJB_05.ear
Dieses EAR funktioniert in JBoss Version 5.0.1 und 5.1.0 (wegen eines Fehlers in den angegebenen Versionen) nicht !
Wenn Sie dieses EAR (Enterprise-ARchive) verwenden können Sie das Client-Programm aus diesem Tutorial unverändert verwenden:
                remoteShowTimeDateBean = (ShowTimeDateBeanRemote)
                    initialContext.lookup("mapped_ShowTimeDateBeanJNDI");
/* Der JNDI-Name in der obigen Code-Zeile setzt voraus, dass die EAR-Datei 'deployed' wurde.
 * Wenn Sie die JAR-Datei deployed haben, setzen Sie die obere Zeile 'unter Kommentar'
 * und entfernen den Kommentar vor der unteren Zeile. */
//                    initialContext.lookup("ejb/ShowTimeDateBeanJNDI");

Prüfen ob das JAR 'deployed' ist

JBoss bietet die Möglichkeit über eine Web-Abfrage die laufenden EJBs zu sehen.
In den folgenden Beispielen ist JBoss auf dem gleichen Computer installiert wie die verwendete Eclipse-Entwicklungsumgebung.
Dazu wird im Web-Browser

eingegeben - damit wird eine Übersicht von JBoss aufgerufen.

In dieser Übersicht sehen Sie eine Liste der laufenden EJB – darunter sollte das 'Java_EJB_05.jar' zu finden sein.


Das Beispiel ist für den JBoss Java Application Server – andere JAS haben ähnliche Abfragen.

Wenn Sie das EJB nicht finden dann wiederholen Sie den Abschnitt Tutorial: Einfache Session Bean, EJB3-Standard (Java_EJB_05) – Packen der Dateien in Java-Archive (JAR) und 'deploy' > JAR-Dateien an den JAS übergeben ('deploy') und beobachten, ob beim 'deploy' Fehler auftreten.

Wenn Sie nicht sicher sind, ob das von Ihnen erstellte EJB fehlerfrei ist, können Sie die Datei Java_EJB_05.jar hier herunterladen und deployen.
Diese Datei wurde mit der JBoss Version 5.0.1.GA getestet.

Prüfen ob die Datei 'Java_EJB_05-client.jar' zur EJB passt

Die Datei mit der (Java-) Interface muss zum 'deployed' EJB passen. Möglicherweise haben Sie die EJB verändert und vergessen, einen 'Build'
der Datei auszuführen (siehe Tutorial: Einfache Session Bean, EJB3-Standard (Java_EJB_05) – Packen der Dateien in Java-Archive (JAR) und 'deploy' > JAR-Datei für Client-Programme erstellen).

Wenn Sie die Datei 'Java_EJB_05.jar' oder 'Java_EJB_05.ear' von dieser Webseite verwenden dann können Sie die passende Datei Java_EJB_05-client.jar hier herunterladen.

Prüfen auf Tippfehler in der Datei 'jndi.properties'

Der Inhalt der Datei 'jndi.properties' ist kritisch weil darin die Parameter für die Verbindung zum JAS enthalten sind.
Der eingegebene Text kann während des Tippens nicht geprüft werden und eventuelle Tippfehler fallen erst auf wenn die entsprechende Klasse nicht während der Laufzeit geladen werden kann oder eine unpassende TCP/IP-Adresse enthalten ist.

Wenn Sie für Ihre Entwicklungsumgebung ebenfalls JBoss oder Glassfish mit den empfohlenen Einstellungen verwenden, dann vergleichen Sie bitte genau den Inhalt Ihrer Datei mit den Werten der Datei 'jndi.properties' in diesem Tutorial.

Als letzte Möglichkeit können Sie die Werte aus diesem Tutorial in Ihre Datei kopieren.

Prüfen, ob die Bibliothek für die Verbindung zum JAS vom verwendeten JAS stammt

Für das Verbinden zum JAS muss die jeweils passende Bibliothek verwendet werden.
Das Einbinden der Bibliothek wurde im Abschnitt Einbindung der Libraries (Programm-Bibliotheken) in den Java Build Path beschrieben.

Eine mögliche Fehlermeldung beim Verwenden einer 'falschen' Bibliothek ist:


Die Fehlermeldung stammt von JBoss Version 5.0.1.GA weil die Bibliothek von JBoss 5.1.0.GA verwendet wurde:


Beachten Sie die Hinweise der (Java-) 'Exception'

Abhängig vom jeweiligen Fehler wird bei der 'Exception' (Ausnahmebehandlung nach einem Fehler' eine Fehlermeldung auf der Konsole angezeigt.
Mit etwas Kombinationsgabe kann meistens aus der Fehlermeldung der Grund des Fehlers erkannt werden.

In diesem Beispiel

wurde
java.naming.factory.initial=org.jnp.interface.NamingContextFactory
statt
java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
als Wert erfasst.

▲ zum Inhaltsverzeichnis

Gesamter Code am Ende des Schrittes

Datei ShowTimeDateClient.java

package js_ejb06.client;
/*
 * Package mit verschiedenen Klassen für Ein- und Ausgabe. */
import java.io.*;
/*
 * Package mit verschiedenen Klassen für die Verbindung zum Java Application Server (JAS). */
import javax.naming.*;
/*
 * (Java-)Interface mit den Länder-Codes und -Langnamen. */
import js_ejb05.staticvalues.CountryConstants;
/*
 * Interface zur EJB die auf dem JAS läuft. */
import js_ejb05.ejb.interfaces.remote.ShowTimeDateBeanRemote;

public class ShowTimeDateClient {

    public ShowTimeDateClient() {
      super();
    }
/* */
    public static void main(String[] args) {
/*
 * Anzahl der Länder-Codes im Array;
 * Index für das Ansprechen der Länder-Codes und Langnamen im Array. */
        int CountryArraySize = CountryConstants.Country.length;
        int CountryArrayIndex = 0;
/*
 * Bauen des Strings mit der Konsol-Ausgabe
 * (Erklärung was als Konsol-Eingabe erwartet wird). */
        String strKonsolErklaerung = "Bitte geben Sie den möglichen Länder-Code [";
        for (CountryArrayIndex = 0; CountryArrayIndex < CountryArraySize; CountryArrayIndex++) {
            strKonsolErklaerung +=
                CountryConstants.Country[CountryArrayIndex][0].trim().toUpperCase();
            if (CountryArrayIndex < (CountryArraySize - 1)) strKonsolErklaerung += ", ";
        }
        strKonsolErklaerung += "] ein oder lassen sie das Feld leer um das Programm zu beenden: ";
/*
 * Variablen für die Eingabe auf der Konsole. */
        String strKonsolAntwort = "";
        byte byteKonsolBuffer[] = new byte[80];
        int intKonsolBufferLaenge;
/*
 * Schleife für das Abfragen der Eingabe auf der Konsole und Aufrufen des EJB. */
        for (;;) {
/*
 * Anzeigen der Erklärung auf der Konsole. */
            System.out.print(strKonsolErklaerung);
/*   */
            try {
/*
 * Antwort (Eingabe auf der Konsole) einlesen. */
                intKonsolBufferLaenge = System.in.read(byteKonsolBuffer, 0, 80);
                strKonsolAntwort = new String(byteKonsolBuffer, 0, intKonsolBufferLaenge);
/*
 * Umwandeln in Grossbuchstaben und führende und nachfolgende Leerzeichen entfernen. */
                strKonsolAntwort = strKonsolAntwort.toUpperCase().trim();
            }
            catch (IOException e) {
/* Unerwarteter Fehler bei der Konsol-Eingabe; Fehlermeldung auf die Konsole ausgeben. */
                e.printStackTrace();
            }
/*
 * Prüfen ob 'leere' Antwort und in diesem Fall Programm beenden. */
            if (strKonsolAntwort.length() <= 0) {
              System.out.println("Programm beendet");
              System.exit(0);
            }
/*
 * Eingabe als Rückmeldung wieder ausgeben. */
            System.out.println("Eingegeben: " + strKonsolAntwort);
/*
 * Beginn des Codes für das Nutzen der Methoden des EJB. */
            try {
/*
 * Objekt der Klasse 'InitialContext' erstellen.
 * Dabei werden die Werte für den Aufbau der Verbindung zum EJB ('Properties', deutsch: Eigenschaften)
 * aus einer Datei eingelesen.
 * Der Name der Datei mit den 'Properties' ist in der Klasse 'InitialContext', die mit dem Java-package
 * 'javax.naming' importiert wird, enthalten – üblicherweise heisst die Datei 'jndi.properties' und
 * wird von den im Beispiel verwendeten JAS (Glassfish und JBoss) unter diesem Namen erwartet.
 * Andere JAS können möglicherweise andere Dateinamen erwarten.
 * 
 * Für die Beispiele in diesem Tutorial wird JBoss verwendet – aber der Code hier ist völlig neutral
 * und für jeden JAS passend.
 * 
 * Das package 'java.naming' ist in der JAR-Datei, die zum verwendeten JAS (Java-Application-Server)
 * gehört, enthalten – für JBoss ist das die Datei 'jbossall-client.jar'.
 * Die Festlegung, dass die Werte für die Verbindung in der Datei 'jndi.properties' enthalten sind,
 * bei JBoss in folgender Kette festgelegt:
 * Bibliothek: jbossall-client.jar (JBoss-spezifisch) >
 * package: javax.naming (Java-spezifisch, für alle JAS gültig – aber vom Hersteller des JAS codiert) >
 * Klasse: InitialContext (Java-spezifisch, für alle JAS gültig – aber vom Hersteller des JAS codiert)
 *  */
                Context initialContext = new InitialContext();
/*
 * Construction der Interface, über die ein Objekt des EJB am JAS konstruiert wird und
 * später dessen Methoden aufgerufen werden.
 * Der JNDI-Name ('ejb/ShowTimeDateBeanJNDI') ist beim EJB festgelegt. */
                ShowTimeDateBeanRemote remoteShowTimeDateBean;
                remoteShowTimeDateBean = (ShowTimeDateBeanRemote)
                    initialContext.lookup("mapped_ShowTimeDateBeanJNDI");
/* Der JNDI-Name in der obigen Code-Zeile setzt voraus, dass die EAR-Datei 'deployed' wurde.
 * Wenn Sie die JAR-Datei deployed haben, setzen Sie die obere Zeile 'unter Kommentar'
 * und entfernen den Kommentar vor der unteren Zeile. */
//                    initialContext.lookup("ejb/ShowTimeDateBeanJNDI");
/*
 * Ausführen der Methode und Ausgabe des Ergebnisses auf der Konsole. */
                String[] result = remoteShowTimeDateBean.getTimeDateString(strKonsolAntwort);
                System.out.println("Result[0]: " + result[0]);
                System.out.println("Result[1]: " + result[1]);
            }
            catch (NamingException e) {
/* Unerwarteter Fehler beim Erstellen des InitialContext oder beim Ausführen der Methoden des EJB;
 * Fehlermeldung auf die Konsole ausgeben. */
                System.out.println("NamingException");
                e.printStackTrace();
            }
        }
    }
}

▲ zum Inhaltsverzeichnis

Datei jndi.properties (bei Verwendung von WAS-CE)

java.naming.factory.initial=org.openejb.client.RemoteInitialContextFactory
java.naming.provider.url=127.0.0.1:4201

Datei jndi.properties (bei Verwendung von JBoss)

java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory
java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
java.naming.provider.url=127.0.0.1:1099

▲ zum Inhaltsverzeichnis

Datei jndi.properties (bei Verwendung von Glassfish)

org.omg.CORBA.ORBInitialHost=127.0.0.1
org.omg.CORBA.ORBInitialPort=3700
java.naming.factory.initial=com.sun.enterprise.naming.SerialInitContextFactory
java.naming.factory.url.pkgs=com.sun.enterprise.naming
java.naming.factory.state=com.sun.corba.ee.impl.presentation.rmi.JNDIStateFactoryImpl

▲ zum Inhaltsverzeichnis

Bewusste Vereinfachungen in diesem Tutorial-Schritt – im Vergleich zu professioneller Entwicklung

Die bisher ausgeführten Schritte zum Entwickeln der Session Bean im EJB3-Standard sind ein typisches Schulungsbeispiel dessen Einfachheit gewählt wurde um das Prinzip von Session Beans zu zeigen – und die Zeit für das Eintippen des Codes kurz zu halten ;-).

Wenn Sie wenig Zeit haben können Sie die folgenden Erklärungen gerne überspringen und mit dem nächsten Tutorial fortsetzen.

Vereinfacht oder nicht behandelt wurden:

• Die Verwendung von 'persistenten' Daten.
'Persistenz' (Englisch: 'persistence') ist ein Begriff der sich im Umfeld von EJB eingebürgert hat und bedeutet, dass Werte von Attributen permanent gespeichert werden.
In anderen Worten:
Der Zugriff auf Datenbanken (ob relational, objekt-orientiert oder sonstige Verfahren) ist beim Entwickeln von professioneller Software unabdingbar.

Das Beispiel dazu folgt im nächsten Schritt des Tutorials.

• Wenn Ihnen die zweite Vereinfachung aufgefallen ist dann war das Durcharbeiten dieses Tutorials wahrscheinlich eine nette Erholungspause für Sie ;-).

Der Name mit dem die EJB in der JNDI (Java Naming and Directory Index) registriert ist, ist fix im Code enthalten.

Im Code der Bean in der Klasse ShowTimeDateBean als Zusatz zur Injection:
/*
 * 'Injection' der Funktionalität für ein 'stateless' EJB. */
@Stateless(name="JavaScout Java_JSF_05 Tutorial", mappedName="ejb/ShowTimeDateBeanJNDI")

Im Code des Client-Programms in der Klasse ShowTimeDateClient :
  ShowTimeDateBeanRemote remoteShowTimeDateBean;
  remoteShowTimeDateBean = (ShowTimeDateBeanRemote)
    initialContext.lookup("mapped_ShowTimeDateBeanJNDI");

Dieses fixe Codieren des Namens beschränkt die Flexibilität beim Einsatz weil auch der JNDI-Name durch die Veränderung von Parametern veränderbar sein soll.
Typisches Beispiel dafür ist Standard-Software die bei verschiedenen Kunden einsetzbar sein muss.
Dabei ist höchst unwahrscheinlich, dass ein fix vorgegebenen JNDI-Name in das Konzept des Kunden passt.
Häufig will der Anwender den JNDI-Namen so wählen, dass erkennbar ist zu welcher Gruppe (z.B. für welchen Geschäftszweck) die eingesetzte Standardsoftware gehört.

Wie auf der EJB-Seite der JNDI-Name in einer Parameterdatei ('ejb-jar.xml') festgelegt werden kann wird im nächsten Schritt des Tutorials gezeigt.

Auf der Seite des Client-Programms kann der JNDI-Name von einer Datei eingelesen werden.
In den Klassen des JavaScout Base-Systems (JSBS) ist in der Klasse JSBS_StartFrame die Möglichkeit vorgesehen, den JNDI-Namen aus der XML-Struktur in der Datei 'Connections.xml' einzulesen.

▲ zum Inhaltsverzeichnis

Weitere Schritte und verwandte Dokumentation

▲ zum Inhaltsverzeichnis