Preparing the Workspace for Apache Tapestry

In the previous article of this series I explained, in the historical perspective, why Tapestry is a very attractive and advanced framework for building Java Web applications. Now we are moving from theory to practice. But before doing anything, we need to prepare the workplace.


Useful items that you will want to download for this article include Tapestry Libraries and source code. These are available at the links shown in zip format.

There are two possible approaches to explaining how to get and install all the necessary pieces of software.

One approach is to describe every step in great detail, with screenshots and extensive comments. However, I expect that many readers will find this approach too tedious, especially when the installation process is straightforward and is also described elsewhere (say, in the documentation that comes with the downloads).

The second approach, and the one that I am going to take, is to explain in detail only those steps in installation and configuration that are not trivial, and give only general directions for the trivial ones.

This second approach, although more efficient, leaves a possibility that some readers will be stuck with a problem of one sort or another. However, DevShed provides a discussion page where everyone can ask a question, and I will be always there to answer it. So I suggest that if you have a problem following my instructions, or any other problem indeed, ask a question at the discussion page, and I will give as detailed explanations there as might be needed.

We shall need the following three pieces of software:

  • Java Development Kit (JDK). This one is needed to make your computer able to compile and run Java programs.
  • An Integrated Development Environment (IDE). The two most popular free choices are NetBeans and Eclipse. I will cover Eclipse configuration in wide strokes, while more detailed instructions will be given for NetBeans configuration only.
  • A servlet container. The most popular choice is Apache Tomcat, and it is also bundled with NetBeans, so this is exactly what we will use for this tutorial.

All of this software is available for free, so you can simply download and install it.

If you will follow my choice of IDE and decide to use NetBeans, there is a way to get everything installed in one go using a bundle. Refer to the instructions below.

{mospagebreak title=JDK}

Before installing a JDK, first of all please check to see whether you have installed it already. To do this, try to invoke the Java compiler. Open a command prompt or a console window and enter the following command:

javac -version

If your computer replies similar to this:

C:>javac -version

javac 1.5.0

javac: no source files

Usage: javac <options> <source files>

where possible options include:

… other output goes here …

then you already have a JDK. Still, check the version. Although Tapestry can work with a version of JDK as low as 1.3, we are going to use annotations in these tutorials, and annotations appeared in version 1.5 only.

If however your computer replies that javac isn’t a recognized command, or your version is lower than 1.5, you need to install an appropriate JDK.

To do this, go to the Java.sun.com website and in the menu choose Downloads > Java SE (http://java.sun.com/javase/downloads/index.jsp).

Here you have two options: to download and install JDK itself (the current version is JDK 6) or download and install JDK together with NetBeans IDE (currently JDK 6 with NetBeans 5.5). The latter makes sense if you agree with my suggestion to use NetBeans as the IDE for this tutorial.

The JDK + NetBeans package is available for Windows, Linux and Solaris only, not for Mac OS X, but Macs have a JDK already installed on them anyway.

If your Mac came with JDK 1.4.2 or earlier on it, please check the Java FAQ at Developer.apple.com (http://developer.apple.com/java/faq/) to find out how to upgrade to a higher version.

After downloading a JDK, please follow the provided installation instructions specific to your platform. Or ask me at the discussion page if you have any difficulties.

If you are installing JDK together with NetBeans, simply accept all the default options during the installation.

{mospagebreak title=IDE}

Eclipse

Eclipse is a very popular tool among Java developers, and if you are used to it, you might prefer to use Eclipse for Tapestry development too.

There are a number of sources explaining how to set up Eclipse for building Tapestry applications. One of them is the book by Kent Tong (http://agileskills2.org/EWDT/index.html) which I have already mentioned in the previous article. You will find detailed instructions on downloading and installing everything in the freely available first chapter of this book.

However, Kent Tong uses a "bare bones" Eclipse, while I find the Eclipse Web Tools Platform more convenient to use for Web development. You can find detailed instructions on how to configure Eclipse WTP for working with Tapestry at the Tapestry Wiki website (http://wiki.apache.org/tapestry/HowToSetupEclipseWtp).

NetBeans

One of the benefits of using NetBeans for this tutorial is that you don’t need to bother downloading and wiring together different pieces of software. In fact, you might have already installed everything you need in the previous section if you chose JDK + NetBeans package.

If not, go to the NetBeans website (http://www.netbeans.info/downloads) and download the IDE for your platform (it is available for Windows, Mac OS X, Linux and Solaris). Then install NetBeans following the available instructions with all default options.

Servlet Container (Tomcat)

Hmm… Almost nothing to write here. If you are using Eclipse, you will find out how to download and install Tomcat following the links given above. If you’ve installed NetBeans however, you already have Tomcat bundled with it.

So let’s go on.

{mospagebreak title=The Standard Structure of a Java Web Application}

Before looking inside of a Java Web application, let’s have a look at the surrounding world. First of all we need to agree on what "application context" means, as this term can have different meanings.

Say we have created an application named TestApp and uploaded it to our server; let its domain name be http://www.example.com/. If someone wants to use our application, they should navigate to www.example.com/TestApp/. We can think that at this location some folder or directory is located that contains all the files of our application. That folder, together with its URL, like http://www.example.com/TestApp/, is the context of our application, and the location of all the files, accessible from the Web, is defined relative to the application’s context.

Say we have a page named somepage.html that is stored at the top level of the application’s directory. Its location within the application will be /somepage.html – relative to the context. Its full URL will depend on the context’s URL; in our example it will be http://www.example.com/TestApp/somepage.html. It is clear, isn’t it?

Another important piece of information to understand is a Web server’s behavior in relation to the default page. Say you decided to navigate to the application’s context: http://www.example.com/TestApp/. This tells the Web server working at www.example.com from which folder to serve pages to you. But which page exactly will it show you now? By default, it will try to find in this folder a page named index.html, or index.htm, and if there is such a page, the Web server will show it. There are also other ways to configure the default page, as you will see later.

But what happens if there is no default page in the application? The Web server will try to show you all the contents of the folder, so you could pick for yourself exactly what you want to see, or, if this is forbidden by its settings, it will report an error.

These are all basics, of course, but it is important to understand them clearly.

Now, how might the contents of a Java Web application’s folder look? Here is an example:

You can see in the picture that TestApp folder contains:

  • A couple of pages: index.html and somePage.jsp;
  • A few directories: images, styles, META-INF and WEB-INF.

The index.html page is the default page; it will be shown by the Web server if no page was specified for the given application context. The JSP page, somePage.jsp shows simply where JSP pages are placed if they are used in the application – directly under the context, as any other pages.

In fact, you can create as many subfolders as you wish and put your HTML and JSP pages into them, as long as you don’t name your subfolders ‘WEB-INF’ or ‘META-INF’.

It is logical, but not required, to put all the application’s images into one folder, in our example images, and to do the same with all the styles, in our example they are put into the styles subfolder.

The special elements of the application are META-INF and WEB-INF directories. As for the META-INF directory, it will simply contain the manifest file, a kind of description of the package that we shall create from our application at a later stage. We shall not discuss it in more detail.

It is the WEB-INF directory which is all-important. It contains all the inner workings of a Java Web application; it is the heart of it.

This is important: you should always name this directory properly: WEB-INF, in all capitals. If you name it ‘Web-inf’ or ‘web-inf’, your application will not work, and it might be difficult to guess why it doesn’t work.

You can see that the WEB-INF directory contains two subdirectories, classes and lib, and a file named web.xml. Again, we have no freedom here; everything should be named as shown, as everything has its special purpose.

The deployment descriptor, which is web.xml file, serves to tell the Web server all of the most important details about our application and its configuration. In one of the next sections we shall look at the deployment descriptor in more detail.

The functionality of the application that we shall create will be implemented as Java classes, and these will go into the ‘classes’ subdirectory.

Finally, we are going to reuse functionality created by other developers — most importantly Tapestry libraries. This comes packed as JAR files and we shall put any libraries we might need into the ‘lib’ folder.

This is the standard structure that every Java Web application should conform to, whether it was built using just servlets or some more advanced framework. Please note that the WEB-INF directory is protected by the server; you cannot navigate into it. For instance, if you try to navigate to http://www.example.com/TestApp/WEB-INF/web.xml, the Web server should tell you that you are wrong. It is only for the Web application to decide how and when to use the contents of the WEB-INF.

So you have installed an IDE and everything required for development. You have a general idea of the structure of the future application. It is the time to create our first Tapestry project. That will be covered in the next article. See you in the next Tapestry tutorial and don’t forget to visit the discussion page.

Google+ Comments

Google+ Comments