[german]wtp+tomcat – Tutorial #1: Ein leeres Projekt.[/german][english]wtp+tomcat – Tutorial #1: our first project[/english]

[german]
Ich bin seit Jahr und Tag begeisterter Nutzer von Eclipse zur Entwicklung von Web-Anwendungen in Verbindung mit Apache Tomcat und den Web Tools, einem Gespann, das so beeindruckend leistungsfähig ist – wenn man erst einmal die Hürde des Ersteinstieges überwunden hat. Und da die Einstiegs-Dokumentation für die Web-Tools nicht besonders aktuell und deutsche Dokumentation für dieses Thema ohnehin kaum verfügbar ist, warum dem nicht ein wenig Abhilfe schaffen … ?

Beginnend mit diesem Artikel sollen (hoffentlich) kurz und bündig einige Aspekte der Entwicklung von JSP/Servlet-basierten Anwendungen für die Kombination Eclipse/Tomcat beleuchtet werden, wobei es mir eher darum geht, einen schnellen Einstieg in die Bedienung des Werkzeuges zu finden, um sich danach den “eigentlich interessanten” Themen (dem eigentlichen Projekt) widmen zu können.

Voraussetzungen

Für dieses Tutorial sollten folgende Grundlagen geschaffen sein:

• Java SDK 5 ist installiert (auf meinem System läuft Eclipse und Tomcat zwar auch mit der Version 6.0, aber dem Vernehmen nach unterstützt Eclipse in den aktuell stabilen Versionen Java 6 nicht offiziell).
• Apache Tomcat 5.5 ist ebenfalls installiert und funktionsfähig (Version 6.0.x wird im stabilen WTP noch nicht unterstützt),
• Eclipse Callisto ist mit den Webtools installiert und nutzbar (Hilfestellung hierbei geben zwei Screencasts zur Installation des Basis-Systems bzw. dem Installieren von Komponenten via Update-Manager)
• Es ist zumindest ein Grundverständnis für die Arbeit mit Eclipse vorhanden (falls nicht, sei etwa dies hier als äußerst kurzer Schnellstart empfohlen).
• Grundlegende HTML-Kenntnisse sind essentiell; zumindest sollte man um SelfHTML wissen. ;)
• Ebenso ist ein prinzipielles Verständnis für Java-Web – Entwicklung zumindest hilfreich.

Im Folgenden soll es darum gehen, ein erstes Projekt mit einem simplen JSP zu erzeugen und innerhalb von Eclipse in einer Tomcat-Umgebung auszuführen.

Server-Runtime

Sinnvollerweise sollte Eclipse mit einem neuen Workspace gestartet werden, um eventuelle Wechselwirkungen mit anderen Projekten und Einstellungen auszuschließen. Um Java-Web-Projekte in Eclipse erstellen zu können, bedarf es zunächst eines grundlegenden Sets von Basis-Bibliotheken, deren Klassen etwa in Servlets und JSPs zur Verwendung kommen. Diese Basis-Bibliotheken beinhalten die Server-Runtime – Definitionen, die sich über “Window -> Preferences -> Server -> Installed Runtimes” verwalten lassen. Über “Add” läßt sich eine neue Server-Umgebung definieren. In diesem Fall soll ein Apache Tomcat 5.5 als Basis für die weiteren Arbeiten dienen:

Image may be NSFW.
Clik here to view.

Weiter mit “Next”, gilt es den Pfad zur lokalen Tomcat-Installation auszuwählen. Dies entspricht dem Installationsordner des Servers bzw. der Umgebungsvariable $CATALINA_HOME:

Image may be NSFW.
Clik here to view.

Nach Beenden mit “Finish” existiert eine Tomcat-Umgebung in “Installed Runtimes”, für die nun Projekte erstellt werden können. Wichtig ist hierbei der Unterschied: Anders als eine Start-Konfiguration für den Server (die später noch erzeugt wird) ist die Server-Runtime selbst kein “Server” im eigentlichen Sinne, sondern lediglich eine Sammlung von Bibliotheken und Infrastruktur, die Web-Projekte benötigen.

Web-Projekt

Anwendungen, die auf einen JEE-Server (oder in einem Servlet-Container wie Tomcat) laufen sollen, existieren in Eclipse unter dem Begriff “Dynamic Web Project”; ein solches läßt sich erzeugen über “File -> New -> Project”:

Image may be NSFW.
Clik here to view.

Das Projekt für dieses Tutorial soll auf den Namen “foobar” hören; darüber hinaus können zunächst die Standardwerte für die Erzeugung des neuen Projektes (die vorher konfigurierte Server-Runtime – Umgebung sollte als Vorgabe eingestellt sein) übernommen und das Projekt mit “Finish” erstellt werden:

Image may be NSFW.
Clik here to view.

Die darauf folgende Frage, ob in die JEE-Perspektive gewechselt werden soll, ist für die Entwicklung von Web-Anwendungen zu bejahen, bevor der Workspace etwa wie folgt aussieht:

Image may be NSFW.
Clik here to view.

Neben einer Reihe von verschiedenen (leeren) Views wartet das neu generierte Web-Projekt im “Project Explorer” auf sinnvollen Inhalt. Wird “foobar” expandiert, zeigt sich, daß Eclipse die folgende Struktur erzeugt hat:

Image may be NSFW.
Clik here to view.

Dem JEE-Entwickler wird der Deployment-Descriptor für die Web-Anwendung (WEB-INF/web.xml) auffallen; darüber hinaus zeigt sich (unter “Deployment Descriptor”) auch eines der Features der Web-Tools, den Inhalt von web.xml nicht nur via XML-Editor, sondern auch “grafisch” bearbeiten zu können.

Zudem existiert auch ein Ordner ‘WebContent’; dies ist der Ort, an dem der Entwickler sämtliche Elemente unterbringen soll, die in irgendeiner Art und Weise zur Anwendung gehören und keine Java-Klassen sind (mithin Bilder, JavaScript-Files, JSPs usw. usf.).

Die erste JSP

Damit das Projekt Inhalt bekommt, soll dort eine simple Startseite untergebracht werden, die (wenig überraschend) eine Abwandlung des klassischen “Hallo Welt” darstellen und (schließlich handelt es sich um einen Server…) den zugreifenden Client mit einem freundlichen “Hallo, IP -Adresse!” begrüßen soll. Dafür zunächst eine leere, neue JSP-Datei, mittels Rechtsklick auf “WebContent”:

Image may be NSFW.
Clik here to view.

Per Standard wird als Startseite eines jeden neuen Projektes die Datei “index.jsp” angenommen; auch hier kann die Erzeugung nach Vergabe des Namens unter Beibehaltung der Standard-Einstellung mit “Finish” beendet werden:

Image may be NSFW.
Clik here to view.

Ist die Prozedur erledigt, zeigt sich im Workspace, daß eine neue Datei “index.jsp” angelegt wurde (wenig überraschend), die mit Standard-Inhalt befüllt und in einem Editorfenster geöffnet worden ist:

Image may be NSFW.
Clik here to view.

Nur ist die Seite so noch nicht allzu sinnvoll. Um minimale Funktionalität unterzubringen, soll der Code wie folgt verändert werden:

• Als Titel für die Seite wird “Demoprojekt” festgelegt.
• In den Inhalt (nach dem HTML-Body-Tag) wird der Code eingefügt, der die definierte Begrüßung ausführen soll.

Image may be NSFW.
Clik here to view.

Damit existiert eine minimale, aber ausführbare Funktionalität, die auch auf dem Server ausgeführt werden kann.

Start des Servers

Eclipse verfügt dazu über projektspezifische Möglichkeiten, Code auszuführen, der generell über die Funktion “Run” erreichbar ist. Für das dynamische Web-Projekt existiert die Konfiguration “Run on server”, die über Rechtsklick auf das Projekt im Workspace ausgeführt werden kann:

Image may be NSFW.
Clik here to view.

Danach kann wahlweise ein bestehender Server ausgewählt oder ein neuer erzeugt werden; da der Workspace zuvor leer war und noch keine nutzbare Start-Konfiguration für einen Server existiert, ist letzteres der Weg. Dazu sollten im folgenden Dialog die Standard-Einstellungen einfach übernommen werden, die Startkonfiguration basiert dann auf der Server-Runtime, die dem Projekt zugrundeliegt:

Image may be NSFW.
Clik here to view.

Nach Bestätigung (“Finish”) wird, je nach zugrundeliegender Hardware, ein wenig Zeit verstreichen, während der Tomcat-Server gestartet und das aktuelle Projekt darin installiert (“deployed”) wird. Sobald dies erfolgreich ist, sollte im Workspace der eingebettete Web-Browser das Ergebnis der Ausführung anzeigen:

Image may be NSFW.
Clik here to view.

Ess zeigt sich:

• Der Server hat, wie gewünscht, die JSP “index.jsp” angezeigt, den darin enthaltenen Code abgearbeitet und zeigt nun hinter “Hallo” die IP des aufrufenden Clients an (localhost, da der Client und der Server auf derselben Maschine laufen).
• Zugriff auf das Projekt via HTTP ist unter der URL http://localhost:8080/foobar/ möglich; “index.jsp” wird dann (als “Welcome-Page” vorkonfiguriert) automatisch angezeigt (http://localhost:8080/foobar/index.jsp hätte denselben Effekt).
• Im “Console”-View im unteren Teil des Bildschirms zeigen sich die Statusmeldungen der laufenden Tomcat-Instanz. Dies wird später noch von Interesse sein, wenn mehr als nur JSPs in der Anwendung arbeiten.

Server-Status und -ende

Ein Klick in den View “Servers” zeigt: Die definierte Konfiguration des Tomcat läuft immer noch, darin das projekt “foobar”. Solang dies der Fall ist, kann mit jedem beliebigen Web-Browser auch außerhalb von Eclipse auf diese Anwendung zugegriffen werden. Aber da dieser Teil des Tutorials hier sein Ende findet, soll jetzt der Server erst einmal sauber angehalten werden, bevor der Workspace geschlossen wird. Dies geschieht über den roten Knopf im “Servers”-View:

Image may be NSFW.
Clik here to view.

Zusammenfassung und Ausblick

Bislang wurde eine Server-Runtime in Eclipse konfiguriert, ein Web-Projekt auf deren Basis erzeugt, darin eine einfache JSP-Seite angelegt und demonstriert, wie das Projekt auf dem Server ausgeführt und durch Clients erreicht werden kann. Damit ist es schon möglich, Anwendungen, die ausschließlich auf JSPs aufsetzen, zu realisieren, ein wenig mit der Technologie “herumzuspielen”, die Umgebung kennenzulernen. Der nächste Schritt wird dann sein, eine Servlet-Klasse in die Anwendung zu integrieren… Kommentare, Kritiken und Fehlerberichte werden gern entgegengenommen. :)

Weiterführende Links

• jsptutorial.org – ein im Werden begriffenes Tutorial zu JSP/Servlet-Technologien, in dem sehr viel mehr Detail-Wissen zur Technologie insgesamt vermittelt wird
• JSP-Tutorial von Daniel Niklas (PDF) – ebenfalls eine exzellente, wenngleich etwas ältere Einführung in das Thema
• kostenfreie (englische) Kurs-Unterlagen zu server-seitigem Java von Marty Hall, dem Autor u.a. von “Core Servlets and JSP”
• JSP-Sektion in den TechDocs von Torsten Horn, eine umfangreiche deutschsprachige Sammlung von Material zum Thema
• ebendort auch ein knapper Artikel zu Eclipse, der allerdings nicht die WTP-Integration, sondern das SysDeo-Tomcat-Plugin zugrundelegt, was die Web-Funktionalität betrifft

[/german]

[english]
For quite a bunch of years now I’ve been using Eclipse and the Eclipse Web Tools as an integrated development environment for building JEE web applications supposed to run on a Apache Tomcat servlet container, and I’ve found this combination of tools to be astoundingly powerful and rather joyful working with – given you once managed to figure out how to do things to make these tools play nicely together. Surely I made use of the Web Tools introductory tutorial, which, then again, left a bunch of questions unanswered especially in relation to the latest stable Web Tools release that comes with Eclipse Callisto. And, initially, I figured out that the amount of German documentation on these things is next to non-existent, that’s why I originally started writing these tutorials in German. …

However, the last few months I learnt that especially this article used to be the most-visited one on [z428] and also used to have a bunch of hits from sites all over the world, and so I decided to do a rough English translation in order to make reading through this a little more enjoyable to visitors not that familiar with my native language. However, this article (and the others likely to follow) are all about pointing out a few things on how to build JSP/servlet based web applications making use of said tomcat/eclipse combination. Think of it as a quick-and-dirty introduction to usage and configuration of the tools in question to not have to deal with this for too long and get started doin’ some real work quickly, indeed.

What do you need?

There is a bunch of preconditions that should be met before making your way through this tutorial:

• You do have Java SDK 5 installed and running on your machine (though my environment successfully runs on JDK6, this is not really supported at least for Eclipse 3.2, and for what we’re about to do here, you won’t need Java 6 anyhow…)
• Apache Tomcat 5.5 is installed and ready to go (the current stable WebTools release doesn’t yet support tomcat 6.0, WTP 2.0 that comes with Eclipse 3.3(Europa) probably will…)
• Eclipse Callisto including the Web Tools package is installed and works (to get this done, in case of trouble have a look at these two screencast outlining installation of Eclipse Callisto base system and component installation using the Eclipse Update Manager)
• You should have some basic understanding of Java development and HTML. Knowing a few general things about Java web development won’t hurt, either.

By now we’re about to create an empty project containing just a simple JSP and run this using a tomcat environment inside the Eclipse IDE. So, let’s get started…

Server-Runtime

Do move on, launching the Eclipse IDE using a new (empty) workspace is a good idea in order to avoid any side effects caused by other projects and/or configurations possibly around in any other workspace. To create Java web projects in Eclipse, the first thing you need is a basic set of libraries providing classes which are needed to create servlets, JSPs, … . These basic libraries, inside Eclipse, are referred to as “server runtime” definition and may be configured using “Window” -> “Preferences” -> “Server” -> “Installed Runtimes”. Choose “Add” to create a new “server runtime”, which, in our setup, should be a tomcat 5.5 environment:

Image may be NSFW.
Clik here to view.

Movin’ on with “Next”, you should specify the path to your local tomcat installation. This is likely to be the tomcat installation folder in your file system (or the value of $CATALINA_HOME if that setting is familiar to you already):

Image may be NSFW.
Clik here to view.

Ending with “Finish”, you do have a tomcat environment in “Installed Runtimes” which, by now, can be used to create web projects. One thing worth noting about this: This “Installed Runtime” is just a collection of libraries and infrastructure but not yet a “real” server configuration to actually run a project on. You will learn how to create a server launch configuration for your project from this definition later on.

Web-Project

Java web applications supposed to run inside a JEE server (or a servlet container like tomcat) are, in Eclipse, referred to as “Dynamic Web Project”‘s. Create one of these using “File” -> “New” -> “Project”:

Image may be NSFW.
Clik here to view.

In this tutorial, the project is named “foobar”… apart from setting the name, by now you can go with the default settings for project creation (you should see the server runtime you just configured already selected for your project) and actually have the IDE create the project choosing “Finish”:

Image may be NSFW.
Clik here to view.

After that, you’re asked whether to switch to the J2EE perspective, which you should do to see an (almost empty) workspace like this:

Image may be NSFW.
Clik here to view.

As you see, aside from a set of different and mostly empty views, there is your shiny new web project to be seen in the “Project Explorer”, waiting to be filled with any (meaningful?) content. Expanding “foobar”, you can have a look at the structure Eclipse just created for it:

Image may be NSFW.
Clik here to view.

Being a JEE developer, you are likely to immediately see the deployment descriptor (WEB-INF/web.xml) for this application. Furthermore, inside “Deployment Descriptor”, you can see one of the Web Tools features to edit web.xml not just using the default XML editor but some rather convenient “visual” tool.

You also might see the “WebContent” folder inside the project: This is the very place to put application components which aren’t Java classes (most likely images, JavaScript files, JSPs and so on…).

Creating our first JSP

Outting some content to the project, we want to create a simple starting page which (not really surprising…) is supposed to be an adaptation of the infamous “Hello World” which (we’re talking about a server application, after all) should welcome its user with a friendly “Hello, client-ip-address!”. To get this done, create a new, empty JSP by right-clicking “WebContent”:

Image may be NSFW.
Clik here to view.

Default web.xml configuration assumes “index.jsp” to be one of the starting pages possible for that application. While creating this first JSP, aside from assigning the right name for now you also can go with the default settings and end JSP creation using “Finish”:

Image may be NSFW.
Clik here to view.

Done that, you will notice that, in your workspace, a new file “index.jsp” has been created (which comes as no surprise…) which, filled with some default content, has been opened in an editor window:

Image may be NSFW.
Clik here to view.

So much for that. As you might see, a page just containing an empty default template still is rather pointless. To add the (minimal) functionality we just defined before, we want to change the JSP markup as follows:

• Page title should be set to “Demoprojekt”.
• The “welcome” code should be added to the page content directly following the “body” tag.

Image may be NSFW.
Clik here to view.

This way, you do have a minimal project containing minimal code which by now might be run using your tomcat installation.

Starting the server

To do so, Eclipse provides project-dependent configurations how to run code, generally accessible using the “Run” option. Talking about a dynamic web project, you’ll in there find the “Run on server” configuration which might be reached right-clicking the project in your workspace and seems the right thing to do:

Image may be NSFW.
Clik here to view.

Following this, you can either choose an existing server configuration or create a new one. Assuming an empty workspace, you don’t yet have any useful server configuration around so you’ll have to create one first. In the window to follow, you should accept the default settings to create a server launcher configuration based upon the server runtime configured for your project:

Image may be NSFW.
Clik here to view.

Accepting this setup (“Finish”), you will have to wait a few moments (depending on your hard- and software environment) for the tomcat server to come up and your project to be installed (“deployed”) in it. As soon as this process comes to an end, you will see the embedded browser window in your workspace show the result of your doings:

Image may be NSFW.
Clik here to view.

So far we see:

• As desired, the server has returned the content of “index.jsp” after processing the code contained within, now displaying “Hallo ” plus the IP address of the client who requested this resource (which, in our case, is “localhost” given client and server run on the same machine…).
• By now you also may access the project using HTTP and your regular browser using right the URL to be seen here (http://localhost:8080/foobar/), instead of making the server choose the “default welcome page” you also could manually request it using http://localhost:8080/foobar/index.jsp.
• Looking at the “Console” view in the lower right of your workspace you can see the status output of your running tomcat instance. This will of interest as our application grows beyond just providing a simple JSP.

Server state and shutdown

Navigating to the “Servers” view, you see that the defined tomcat configuration is still running, same as the “foobar” project inside of it. As long as things are this way, you can access the project using any web browser both inside and outside of Eclipse. But as we reached the end of the first part of this tutorial, by now we want to shut down the tomcat server before closing the workspace. To do so, use the “big red button” in your “Server” view:

Image may be NSFW.
Clik here to view.

What’s next?
By now we set up a server runtime in Eclipse, created a simple project based on it, built a very simple JSP page and looked at how to get this project to run on a server and access it using arbitrary clients. This way, we’re already capable of building applications solely relying upon JSPs and to “play around” with that technology a little, to learn more about our working environment. Next step will be to add a servlet class to this application… By now, thanks a lot for your interest, and please feel free to give me any kind of feedback on that article, both about the content and about the “English” translation.

Things worth reading

• course papers on server-sided Java by Marty Hall (know i.e. as author of “Core Servlets and JSP”)
• Java Server Pages Technology chapter in Sun’s official J2EE 1.4 tutorial

[/english]