[digital:meditation]

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:

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

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

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

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

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:

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

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

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:

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.

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:

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:

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:

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:

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