keyboardsamurais.de thoughts on software development, warts and all…

Tomcat Tutorial: HelloWorld for Complete Fools ;-)

This Tutorial is also available in English here

Update 26.02.2007: Obwohl die Grundlagen dieses Artikels immer noch gelten und richtig sind, gibt es mittlerweile einige Entwicklungen an der Eclipse Platform die es sich lohnt anzuschauen. Insbesondere die Eclipse Web Tools Platform. Ich habe zu diesem Zweck einen Screencast erstellt der eine Einführung in das Entwickeln mit WTP gibt. Ihr findet ihn in diesem Artikel.

Ich kenne einige erfahrene Java Entwickler, die bereits daran gescheitert sind ein eigenständiges Servlet Projekt auf Apache Tomcat Basis einzurichten. Entwickler, die komplexeste Neuronale Netze wie im Schlaf entwickeln und die EJB Spezifikation rückwärts beten können, haben hier schon ihre Probleme gehabt. Man kann also mit Recht sagen, daß es nicht selbsterklärend ist ein Servlet auf dem Tomcat Container zur Mitarbeit zu überreden. .WAR Archive deployen an sich kann jeder, aber ganz anders sieht das aus wenn ein
brandneues Projekt in einen eigenen Context gesetzt werden soll und die Verzeichnisstruktur entsprechend der Spezifikation erstellt werden muss et cetera, et cetera, et cetera. Als Neuling muss man sich also erst Recht nicht schämen, wenn man Anfangsproblemchen mit Servlets hat.

Um diese Anfangsschwierigkeit zu mildern habe ich dieses Tutorial geschrieben.

Dabei ist es eigentlich höllisch einfach so ein Servlet zum laufen zu bringen - vorausgesetzt man kann bei jemandem Nachfragen, der bereits die hohe Kunst der Tomcat Administration beherrscht. Ich kannte niemanden, der das konnte und habe ewig lange Zeit damit verbracht jeden Fehler den ein Anfänger begehen kann zu begehen. Daher weiß ich wovon Ich spreche wenn ich sage, die Konfiguration von Tomcat ist ohne Unterstützung einer kundigen Person, selbst unter Zuhilfenahme von Google alles andere als trivial.

In diesem Tutorial werde ich versuchen so detailliert wie möglich zu erklären wie man step-by-step vorgeht um ein simples “Hello World” Servlet unter Tomcat 4 zum laufen zu bekommen. Für das Tutorial verwende ich Eclipse und Eclipse Spezifische Plugins. Ich hoffe dennoch, daß man sich aus den Darstellungen die generelle Vorgehensweise abschauen kann um das gleiche auch für andere Entwicklungsumgebungen zu bewerkstelligen. Es wird hierbei vorausgesetzt, daß die Installation von Eclipse und der Umgang
mit Plugins geläufig sind.

Folgende Software wird also zunächst benötigt:

• Tomcat Servlet Container
• Eclipse 3.X
• Sysdeo Eclipse
  Tomcat Launcher plugin

Der Server

Tomcat zu installieren ist besonders für Windows Benutzer recht einfach, da ein guter Installer alle Konfigurationsarbeit abnimmt. Alles was man noch zu tun hat ist, sich das Admin Passwort und Verzeichnis zu merken in das Tomcat installiert wurde.

Das Plugin

Das Sysdeo Tomcat Plugin ist unser Freund und Helfer. Nachdem es installiert wurde erscheinen prompt folgende Buttons und Menüs in der Bedienleiste von Eclipse.

Die drei Kater bedeuten in der Reihenfolge von Links nach Rechts Start, Stop und Neu starten. Noch funktionieren sie nicht, denn wir müssen zunächst noch einige Einstellungen vornehmen. Hierzu gehen wir in das Menü “Window-> Preferences” dort öffnet sich nun folgender Dialog

Vergrössern

Im Menüpunkt Tomcat tragen wir nun ein, welche Version von Tomcat wir benutzen. Zum heutigen Zeitpunkt ist das die 4.1er oder die 5er Version. In das Feld “Tomcat
Home” geben wir das Verzeichnis ein in das Tomcat installiert wurde. Der Pfad zur Konfigurationsdatei server.xml wird nach der Eingabe des
“Tomcat Home” automatisch ergänzt. Eclipse wird fortan für uns diese Konfigurationsdatei verwalten, in der zum Beispiel der <context> einer Applikation gesetzt wird.

Ein Tomcat Server besitzt verschiedene Benutzerrollen. Einen besonderen Benutzer, den “Administrator”, haben wir bereits bei der Installation angelegt. Seine Benutzername und sein Passwort finden sich in der Datei tomcat-users.xml. Ein weiterer Benutzer ist der Benutzer “Manager”, er ist nach der normalen Installation noch nicht angelegt und muss manuell hinzugefügt werden. Diese Arbeit nimmt uns Eclipse allerdings ab, wenn wir nun die Untermenüs von Punkt Tomcat aufklappen und dort den Punkt “Tomcat Manager App” aufrufen. Hier kann nun ein Benutzername und ein Passwort für den Manager festgelegt werden. Anschließend auf den Button “Add user to tomcat-users.xml” clicken und dir Konfiguration verlassen.

Vergrössern

Jetzt können wir zu Probehalber Tomcat starten. Hierzu clicken wir auf den oben genannten Knopf auf dem der Tomcat Kater abgebildet ist. Wenn Tomcat ohne jegliche Stacktraces hochfährt und wir uns jetzt mit dem Browser auf http://localhost:8080/ verbinden können und unten stehende Startseite sehen ist alles in Ordnung.

Hello World

Jetzt beenden wir Tomcat allerdings erstmal wieder. Und widmen uns unserem ersten Servlet. Hierzu erzeugen wir ein neues Projekt im Navigator Fenster

Im Projektfenster wählen wir jetzt Tomcat Projekt aus…

…clicken auf “Next” und benennen unser Projekt.”HelloWorld”

Nach einem click auf “Next” können wir nun angeben unter welcher
URI (Uniform Resource Identifier) wir unsere Anwendung im Browser künftig ansprechen wollen. Dies entspricht dem im Folgenden, dick gedruckten Teil in
unserer Adresse: http://localhost:8080/HelloWorld/hello Wir belassen alles so wie es ist. Daß bedeutet wir lassen Eclipse die
XML Dateien von Tomcat verwalten und legen für unsere Applikation fest, daß sie nicht in einem Unterverzeichnis sondern im Hauptverzeichnis abgerufen werden soll. Es sollte also so aussehen wie auf folgender Darstellung.

Vergrössern

Wenn wir nun den Wizard mit “Finish” beenden, so sehen wir das Eclipse uns gleich eine ganze Sammlung an Verzeichnissen angelegt hat. Es sollte wie
folgt aussehen.

Im Verzeichnis WEB-INF/src legen wir nun eine neue Klasse an, die wir HelloServlet nennen. Der Code, für diese Klasse sieht folgendermaßen aus.

import java.io.*;

import javax.servlet.http.*;
import javax.servlet.*;

public class HelloServlet extends HttpServlet {
  public void doGet (HttpServletRequest req,
                                         HttpServletResponse res)
        throws ServletException, IOException
  {
        PrintWriter out = res.getWriter();
        out.println(”Hello, Brave new World!”);
        out.close();
  }
}

Unsere Ansicht sieht also nun so aus.

Vergrössern

Leider ist es damit allerdings noch nicht getan. Zunächst müssen wir noch den web.xml Deskriptor anlegen der u.a. angibt unter welchem Namen wir das Servlet über den Browser ansprechen können. Die Datei
web.xml muss im Verzeichnis WEB-INF angelegt werden ( NICHT IM VERZEICHNIS WEB-INF/src !!!). Für
unsere Anwendung sollte sie folgende Einträge enthalten.

<!DOCTYPE web-app PUBLIC
  '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN'
  'http://java.sun.com/dtd/web-app_2_3.dtd'>
<web-app>
  <servlet>
    <servlet-name>hello</servlet-name>
    <servlet-class>HelloServlet</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>hello</servlet-name>
    <url-pattern>/hello</url-pattern>
  </servlet-mapping>
</web-app>

Hierzu ist zunächst eine kleine Erklärung notwendig. Der Doctype tag gibt an wo sich die Ãœberprüfungsregeln zu unserem xml Dokument finden. So kann man sicher gehen, daß sich keine falschen Parameterkonstellationen einschleichen. Der Haupt Tag <web-app> enthält alle sonstigen Einstellungen. Im Tag Servlet wird vor allem der Name (<servlet-name>) mit dem das Servlet innerhalb des XML Dokuments fortan benannt wird, mit der Klasse (<servlet-class>) verknüpft. Im Tag <servlet-mapping> geht es darum dem Server mitzuteilen welchen Dokumentnamen unser Servlet bekommen soll, wenn man es schließlich über die Browserzeile aufruft. Wichtig ist hierbei, daß man die Reihenfolge in der die Tags geschrieben sind beachtet. Tomcat achtet penibel genau, daß die Reihenfolge eingehalten wird. So muß <servlet> immer vor dem <servlet-mapping> definiert worden sein, und <servlet-name> muss in <servlet-mapping> vor <url-pattern> stehen. Wenn wir jetzt alle Schritte richtig augeführt haben, können wir endlich Tomcat starten. Unsere Umgebung sollte nun folgendermaßen aussehen.

Vergrössern

Wenn wir jetzt die Kombination aus der URI und dem <servlet-mapping> in der Addresszeile des Browsers eingeben, also in unserem Fall die Adressehttp://localhost:8080/HelloWorld/hello sollten wir nun endlich die Ausgabe unseres Servlets sehen können. Hurrah!

Vergrössern

Wer unter Tomcat auch JSPs verwenden will, der kann einfach folgende Zeilen zur web.xml datei hinzufügen und anschließend die JSP Dateien im Hauptverzeichnis des eclipse projektes ablegen.

    <servlet>
        <servlet-name>jspAssign</servlet-name>
        <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
        <init-param>
            <param-name>logVerbosityLevel</param-name>
            <param-value>WARNING</param-value>
        </init-param>
        <init-param>
            <param-name>fork</param-name>
            <param-value>false</param-value>
        </init-param>
        <load-on-startup>3</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>jspAssign</servlet-name>
        <url-pattern>/*.jsp</url-pattern>
    </servlet-mapping>

Die weitere Entwicklung von Servlets unter Eclipse ist übrigens sehr angenehm. Die meisten einfachen Codeänderungen, werden beim speichern in den Servlet Container übernommen, so daß man nicht jedes Mal den Server neu starten oder ein neues Deployment anfangen muss. Viel Spaß mit der weiteren Entwicklung.