Step-by-Step Jakarta Tapestry

The Jakarta Tapestry framework is a hidden treasure of Java web development. It greatly simplifies the work of both web designers and developers. It offers significant convenience by transparently handling much of the boring "plumbing". It even changes the paradigm of web development (at least in terms of the presentation tier) to one that is more natural.

Yet Tapestry remains more or less unknown to a great majority of web developers, for numerous reasons. The most obvious is Tapestry's legendary "steep learning curve" which, in my opinion, is more myth than reality: Tapestry is in fact easier to learn and use than are many other frameworks. Yes, internally Tapestry is more complex than its predecessors, in the same way that a contemporary camcorder is much more complex than those mechanical devices that our grandfathers used to produce their amateur movies. But is a camcorder more difficult to use? No, it is much, much easier (believe me -- I've tried both types of devices).

All right, enough brainwashing, let's jump straight in! By the end of this tutorial, you'll be able to decide for yourself just how easy Tapestry is to use. We won't be creating the traditional 'Hello World' web application here -- that really would be too trivial with Tapestry. We'll start with something more realistic: a login form.

On our way to unraveling the wonders of Tapestry, we need to pass through a kind of purgatory -- the process of creating of a working, Tapestry-ready configuration on our computers. This is more or less standard practice for Java web development, so we'll make it as simple as possible.

If you've ever tried any kind of Java Web development -- using servlets, JSP or Struts -- chances are that you'll already have most of the necessary components on your machine. But if not, don't worry: we'll install everything very quickly and easily. In fact, the installation is mostly about downloading and unpacking ready-to-use pieces of software.

Requirements

We'll need the following:

• Java Development Kit (JDK)
• Tomcat Web server
• Eclipse Integrated Development Environment (IDE)
• Spindle plugin for Eclipse IDE
• Tapestry-specific libraries

If you already have some of these components installed on your computer, just skip the appropriate part of the instructions that follow.

Although Tapestry 4 has just been released, we'll start from the third version of the framework. Many concepts of Tapestry development are more or less the same in both versions -- especially from a beginner's viewpoint. Additionally, Spindle, a very convenient and helpful tool for Tapestry development, is currently only available for Tapestry 3.

What we are going to do now may not seem very exciting, but we need to do this just once. Some of the following instructions are platform-specific -- choose whichever are appropriate for you.

Installing the JDK

If you've ever tried your hand at Java development, you'll already have a JDK installed on your computer. It comes pre-installed with the latest versions of Mac OS X. To verify whether you have it or not, try the following.

In Windows, choose Start > Run..., then type cmd and press the OK button. In Linux or Mac OS X, simply open a terminal window.

Enter the following command at the prompt:

javac

Press Enter. If your computer has a JDK installed and configured, you will see more than a dozen lines of output, beginning with the following:

Usage: javac <options> <source files>
where possible options include:
 -g                        Generate all debugging info
... more lines of output ...

If your computer didn't recognize the command, you'll need to install a JDK. You could install either the latest version, JDK 5.0, or the previous one, JDK 1.4.2. Both are fine for the purposes of this tutorial. Let's assume that you're going to install the most recent version.

1. Download the JDK

For Windows and Linux: download the recent version of JDK 5.0 (at the time of writing, it's JDK 5.0 Update 6). Please note: you will need the JDK, not the JRE!

Some advice for Linux users: whichever distribution you use, you might wish to download the Linux self-extracting file (jdk-1_5_0_06-linux-i586.bin), not the Linux RPM self-extracting file (jdk-1_5_0_06-linux-i586-rpm.bin). In some cases, the former is easier to install and configure.

For Mac OS X: You may not need to download anything, as you probably already have something like the JDK 1.4.2_09 installed on your computer. If you want the new version of the JDK, download it here. However, be warned that changing the default version of the JDK in Mac OS X is not a trivial task, so for the purposes of this tutorial, you might want to stick to the pre-installed JDK 1.4.2.

To better understand the problems running Java 5 on Mac OS X, refer to this discussion at the Javaranch.com forum.

2. Install the JDK

With Windows and Mac OS X versions, you aren't given many choices; just launch the executable file you've downloaded, and follow the instructions.

In Linux, you'll need to change permissions for the downloaded file in order to be able to execute it:

chmod +x jdk-1_5_0_06-linux-i586-rpm.bin

Then, execute it:

./jdk-1_5_0_06-linux-i586-rpm.bin

Once you agree to the terms and conditions that are shown to you, the file will unpack itself. Move the resulting directory, jdk1.5.0_06, to the location where you want it to live (e.g. to /usr/java).

Now, you need to add the bin subdirectory (say, /usr/java/jdk1.5.0_06/bin) to the PATH of your machine. One way you can accomplish this under Linux is to add the following two lines to your .bashrc file (if you use bash, of course):

PATH=/usr/java/jdk1.5.0_06/bin:$PATH
export PATH

That's it! If you followed these instructions correctly, you should have the JDK installed.

Installing Tomcat

Strictly speaking, Tomcat is much more than a web server -- it's what's referred to as a servlet container, which works as a gateway between the world of Web and the world of Java. But it has a decent web server in it too, at least for development purposes. Installing Tomcat is very easy, but we do need to configure an environment variable afterwards.

1. Download Tomcat

This step is common for all the platforms, as Tomcat is a Java program! Go to http://tomcat.apache.org. If you've got JDK 5, choose the latest stable version of Tomcat (at the time of writing, this is 5.5.12), otherwise download Tomcat 5.0.28 -- for our purposes it will work exactly the same.

2. Unpack Tomcat

Unpack the downloaded package into a directory of your choice. This might be c:\apache-tomcat-5.5.12 on a Windows computer, something like /home/alex/apache-tomcat-5.5.12 under Linux, or /Users/alex/jakarta-tomcat-5.5.12 under Mac OS X. The installer wizard for Windows makes this process even easier.

3. Set the JAVA_HOME Environment Variable

This environment variable should point to the directory into which you've placed your JDK. Since we're dealing with the computer's operating system at this point, the following instructions are platform-specific.

Windows XP

Your JDK may have been installed automatically, but it's not difficult to find out where it was installed. It most probably lives in the C:\Program Files\Java directory, so your environment variable should point to something like this:

C:\Program Files\Java\jdk1.5.0_06

To set the variable, right-click on My Computer and select Properties. In the dialog that opens, choose the Advanced tab, then click the Environment Variables button at the bottom.

The System Variables are listed in the lower portion of the window (see Fig. 1). If you don't see JAVA_HOME there, create it by pressing the New button, otherwise edit it as needed by pressing the Edit button.

Fig.1. Setting JAVA_HOME in Windows XP

Linux

If you installed the JDK as described above, you'll know where it is. Otherwise, you might need to find it using the following command:

which java

This will display something similar to this:

/usr/java/jdk1.5.0_06/bin/java

Your JAVA_HOME should therefore point to /usr/java/jdk1.5.0_06.

There are several places where you can set an environment variable in Linux. My preferred option is to edit the .bashrc file, adding the following line:

export JAVA_HOME=/usr/java/jdk1.5.0_06

Mac OS X

The Mac OSX process is mostly the same as the one we used for Linux, the difference being that finding the location at which your JDK is installed is more difficult on Mac. To find out, type:

which java

This will give you something like:

/usr/bin/java

In this case, your JAVA_HOME should point to /usr.

To set the variable, edit your .bash_profile file and add to it the following line:

export JAVA_HOME=/usr

4. Test it!

To test whether or not your installation of Tomcat really works, go to the bin subdirectory of the directory where you installed Tomcat. In other words, if you've installed Tomcat into c:\apache-tomcat-5.5.12, go to c:\apache-tomcat-5.5.12\bin.

There, you'll find the following scripts: startup.sh and shutdown.sh (for Linux and MacOS X usage) and startup.bat and shutdown.bat (for Windows).

Note that on a Linux or Mac OS X machine you may need to change the permissions of all the .sh scripts in this directory in order to be able to execute them, but that's easy:

chmod +x *.sh

To start Tomcat, launch startup.sh or startup.bat (depending on your platform), wait a few seconds, then navigate your web browser to http://localhost:8080. If everything's functioning correctly, you'll see a page similar to Fig.2.

Fig.2. If you see this page, your Tomcat was installed successfully.

In the world of networking, localhost refers to your own computer, when it's referred to as a server. When you navigate to localhost:8080, you are actually asking your computer if anybody is listening on port 8080 (ports on your computer are like telephone extensions inside your office). And this is where Tomcat is listening, by default, so it shows its face.

To stop Tomcat when you don't need it any more, use the shutdown.sh or shutdown.bat scripts. If you used the Windows Tomcat installer, you'll also have a handy little monitoring tool that sits in your task bar. You can use this to start and stop the server.

Installing Eclipse

An efficient and convenient IDE greatly enhances a developer's productivity, and when it comes to Tapestry development, the natural choice of IDE is Eclipse, primarily because the Spindle plug-in we're going to use only exists for Eclipse, but also, of course, because the Eclipse is a superb IDE!
Installing Eclipse is very simple. Go to the Eclipse downloads page and download the version that suits you, for example eclipse-SDK-3.1.1-win32.zip for Windows, eclipse-SDK-3.1.1-macosx-carbon.tar.gz for Mac OS X, or eclipse-SDK-3.1.1-linux-gtk.tar.gz for Linux. Unpack the download to the directory of your choice, e.g. c:\eclipse or /Users/alex/eclipse.

You can start the IDE by launching Eclipse.app in Mac OS X, eclipse.exe in Windows, or by typing eclipse in Linux. When you start Eclipse for the first time, you'll be asked to choose your workspace -- the directory in which all your Eclipse projects will be stored. You can choose either the default directory, or a different one.

That's it! Now we've got the JDK, Tomcat and Eclipse, all of which are prerequisites for general Java Web development. Now, we're going to enrich our work environment with a few Tapestry-specific components.

Installing Spindle

This Eclipse plug-in greatly simplifies Tapestry development, and it's quite easy to install.

Open your Eclipse IDE. Choose Help > Software Updates > Find and Install...

Figure 3. Selecting to install Spindle

In the dialog that appears, select Search for new features to install and press Next. In the next window, press the New Remote Site... button. Enter Spindle for the Name and http://spindle.sf.net/updates for the URL, then press OK and Finish. You will be prompted to select a mirror; select the closest location to you and press OK.

Eclipse will search for the plug-in and show you the result, as shown in Figure 3 above. Select Spindle and press Next.

In the next dialog, accept the terms in the license agreement and press Next. Finally, press Finish. Eclipse will download everything it needs to install Spindle (this could take half an hour or more, depending on your connection). It will then ask you to verify that you really want to install 'an unsigned feature' (see Fig.4).

Choose Install All and, when the installation completes, agree to restart your workbench.

Great! Now your IDE is ready for Tapestry development. The very last step we need to take is to download all the libraries that Tomcat needs to run a Tapestry Web application, and place them in an appropriate location.

Figure 4. Installing Spindle: Verification Stage.

Downloading Tapestry and Other Libraries

Tapestry 3 itself comes in two .jar files: tapestry-3.0.3.jar and tapestry-contrib-3.0.3.jar. But it also relies on other libraries, some of which are included in its distribution, while others need to be downloaded separately. The easiest way to get all the necessary libraries is to download the tapestry_libs.zip archive that I have created for you.
Unpack all the contents of this archive into the shared/lib directory under your Tomcat installation. It can be, say, c:\apache-tomcat-5.5.12\shared\lib on a Windows machine or /Users/alex/jakarta-tomcat-5.5.12/shared/lib on Mac OS X.

Whew, we've done it! We're now ready to unleash the magic of Tapestry.