I think that most people would agree that customer acceptance depends to a large extent on the first impression of the user with the particular product. The first contact with your software however, typically is the installation procedure. With java software and the advent of so called "Platform independent" solutions various attempts to address installation facilities have been tried, but just too often, java coders tend to neglect this duty shamefully. Pretty often you find yourself with some classes and jar files you need to copy all over your system, add extensions to your classpath and finally launch the app from the command line via :java classname just to watch it fail a dozen times before you discover that you forgot to add the -Djava.library.path property to the command line (as stated in the readme.txt at line 1846).

The Installer
Windows users can be very choosey about standardized installation procedures, thus I would recommend using a native Windows Installer like the Nullsoft Install System to create an installer (i.e. a Setup.exe) for your application that can be installed and uninstalled properly in a standard, Windows way^tm. NSIS offers a pretty cool, powerful macro language for installers that you fortunately don't really have to learn to create your typical basic installer. For the average installer it is sufficient to use the really cool wizard option of the magnificent open source Installer editor HM NIS Edit by Hector Mauricio Rodriguez Segura and just take your setup.exe and go. You can easily build really complex installers with custom controls with this tool as well - sky's the limit.

Launching the app
Launching your java application is the next experience the user comes in contact with. If you choose to launch your application through some batch files or worse, let the user start the app through command line as mentioned above, you will most definitely burn in coder hell - and rightly so. There are quite a number of really useful java launchers out there that make launching a java app no less pain than a double click, though the application may actually have serious amounts of dependencies. My favourite one is the Marner Java Launcher by Jacob Marner. It is basically a small executable program written in C, that launches your java VM with all your previously configured options.

Let's assume following example: You wrote a small app that uses a couple of java libraries and utilises the Eclipse SWT framework for the GUI. Now you want the java launcher to do all your bidding. Your first step should be to create a folder at the root of your project directory called libraries and copy jface.jar, swt.jar and whatever libraries you desire into it. Also, you should copy the native SWT dlls into a separate folder called native. In our case this would be swt-awt-win32-xxxx.dll and swt-win32-xxxx.dll from the eclipse directory eclipse\plugins\org.eclipse.swt.win32_x.x.x\os\win32?. Now we have gathered our source code, the dependent libraries and the native components in one directory.

Now we should create a jar file from our source code that contains a file in the root directory called manifest.mf file. The manifest.mf file contains information which Class should be launched as an entry point into our application (i.e. which class contains the main() method. Also it adds our dependent libraries from the libraries folder to our classpath. The manifest.mf file should look like this:

Manifest-Version: 1.0
Main-Class: de.keyboardsamurais.ApplicationMain
Class-Path: ./libraries/xmlrpc-1.2-b1.jar ./libraries/jface.jar ./libraries/log4j-1.2.8.jar ./lib/swt.jar

Eclipse Users can use the "Export" feature for the jar packaging. Now we are able to call our class from the command line via the call java -jar application.jar. Well...almost! Our application still lacks the native DLL components, so we need to tell the VM where they can be found via a -D flag. We can enter java -Djava.library.path=./native/ -jar application.jar and our app should run flawlessly.
Now, that's the point where we configure the launcher.cfg file from our java launcher. For our example this config file would look like that:

.
javaw.exe
-Djava.library.path=./native/ -jar application.jar

If you do need an output window for log messages you can exchange javaw.exe for java.exe. You can now click on the Launcher.exe (which you should have copied into your project directory by now) and your application will run like a charm.

You can now wrap it all up into a nice installer and everybody will have a pleasant experience with your software deployment. You might want to change the icon of your launcher.exe to something more fitting. I recommend doing this with Resource Hacker by Angus Johnson.

Last words
Be aware that there are more than a few other options to do all of the above mentioned steps. One of the most promising install systems is Java WebStart and there are a couple of multi platform installers that promise "Write once, run anywhere". However I am quite happy with the above solution.

Update 26.02.2007: Note, that this Article, though technically still relevant and valid, is not up to date with the progress of the eclipse platform. I created a screencast to reflect the changes that took place and to show you development with the Eclipse WTP. Click here for the article.

I know quite a number of java developers who, despite their good knowledge of the java platform, somehow failed to successfully deploy a new Servlet to a Apache Tomcat installation. I stress, that they did not fail because of their inferior skills, but because of the fact, that there is no comprehensive
resource out there that explains the Tomcat deployment procedure:

• in a nutshell
• with pictures
• without going into details that aren't of direct interest

So, without much further ado, I will try to explain how to install tomcat, create a deployment structure using Eclipse and writing a simple HelloWorld Servlet.

In theory, deploying a Servlet is a really straightforward task - that is, if you know somebody who is willing to introduce you into the deployment mysticisms of the Apache Tomcat development. Unfortunately, I knew nobody who was really adroit with that. So I spent a really long time running into every single ambush Tomcat has to offer for blue eyed newbies. Hence I can rightly say, that Tomcat's configuration is a pain in the rear if you don't have an expert person who guides you through your very first steps. Even if you know your Google search words cold, you won't find a single document that makes your task seem trivial.

So I figured, it would be best for newbies and the like, if you could just follow an example with pictures in it. In the following tutorial, I will try to explain the deployment procedure from the very beginning in step-by-step fashion to build a standard "Hello World" Servlet. To accomplish this, I will use the Eclipse IDE and Eclipse specific plugins, but I hope that one can understand the general proceeding that is necessary for other IDEs as well. I will assume that you are familiar with the installation of eclipse and eclipse plugins.

The following software will be neccessary to follow the tutorial:

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

The Server

Especially for Windows users it's pretty easy to install Tomcat, because there it has a straightforward installer script that rids you of most of the configuration work. Everything you have to do is set the Administrator password (and remember it!) and the installation directory (and remember it!).

The Plugin

The Sysdeo Tomcat Plugin is our best friend. After you have installed it, you will notice these buttons and menues in your IDE.

Enlarge

Enlarge

Hello World

For now, we stop out Tomcat server and take a look at our very own, first servlet. First, we need to open a new project in the navigator window.

...click on the Next button and call our new project "Hello World"

Enlarge

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();
  }
}

Our View should now look like this:

Enlarge

<!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>

What follows now is a little explanation of what we just copied and pasted into web.xml . The Doctype is an xml specific item that tells the xml parser where to look
for the dtd consistency rules for our xml document. The dtd ensures that no wrong parameter combinations are entered. The main tag <web-app> contains all preferences for our servlet. The <servlet> tag basically contains the name (<servlet-name>) that will be used throughout the xml document to reference our servlet and its linked class (<servlet-class>) . The tag <servlet-mapping> is responsible for telling the server, to what document name in the URL our application should respond to. Note, that the correct order of these tags has to be retained to form a valid web.xml descriptor. If we followed all steps correctly, we should now be able to fire up Tomcat again. Our workspace should now look like that:

Enlarge

Enlarge

    <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>

For further reading, I recommend following Sites:

Tomcat 4.1 Documentation
Advanced JSP and Servlet Tutorial

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.