HomeApache Page 4 - Preparing the Workspace for Apache Tapestry
The Standard Structure of a Java Web Application - Apache
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.
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.