HomeApache Page 3 - Creating Your First Tapestry Project
Deployment descriptor - Apache
In the previous article, we began moving from theory to practice by preparing our work place and setting up our system. In this article, we actually get our hands dirty (at least figuratively) by building our first Tapestry project.
The next task is to configure the deployment descriptor in a Tapestry specific way. A deployment descriptor is an XML file and I am used to editing it by hand, but NetBeans provides a handy and easy to use editor for this purpose. Double-click web.xml file, and you will see the editor:
We don't have to enter anything at the first page, although you might want to enter the application's name into the Display Name box. The really important page is the next one, Servlets. Tapestry comes with a ready to use servlet; all we need to do is configure it properly.
Right now, the Servlets page is almost empty, so press the Add Servlet Element... button. In the Add Servlet dialog that opens, enter the information as shown here:
As you will see in a later tutorial, it is convenient to give the servlet the name of the application itself. The Servlet Class will be always the same for all of our Tapestry applications. Now, the important piece of information is the URL Pattern(s). It tells the servlet container exactly which requests should be passed to our servlet. The pattern specified here is understood relative to the application context. This means that if we host our application at the www.example.com server, all requests to http://www.example.com/FirstTapestry/app will be passed to the Tapestry servlet, and the Tapestry framework will step in and show its miracles.
You might have noticed that sometimes I refer to Tomcat as a server, while at other times as a servlet container. In fact, it is both. A Web server is a piece of software that serves Web pages to site visitors. A servlet container is a piece of software that knows how to deal with servlets -- and other Java classes as well. A combination of a Web server and a servlet container, like Tomcat, allows Java Web applications to run on the Internet.
Tomcat is the most popular choice but not the only one. The other quite popular and free option is Jetty. Yet another choice, Gaucho Resin, is not free but has a very good reputation.
Application servers like JBoss, Geronimo, WebSphere or WebLogic have in them a Web server and a servlet container as well, but they also have plenty of other goodies in addition to them. By the way, JBoss, Geronimo and WebSphere Community Edition all use Tomcat for their servlet container.
Press the OK button in the Add Servlet dialog. You will see that the information we have just entered is now shown on the Servlets page. The last piece of the configuration will deal with the default page of the application. Click on the Pages tab of the Deployment Descriptor editing tool, and you will see the page for editing welcome files:
You remember that when no specific page is mentioned in a request, for example a visitor of our application is trying to navigate to http://www.example.com/FirstTapestry/, the Web server needs to decide which page to show. Here we can configure this, and currently the index.jsp page, generated automatically by NetBeans, is the only option.
If we wanted to have some default page which is not a part of the application itself, we could perhaps use the existing one, or use a static page, like index.html, and on it we could provide a link to the Tapestry application, i.e. to the Tapestry servlet.
However, in many cases we will want our Tapestry application to step in straight away, without any additional pages on the way to it. Let me show you my favorite trick to achieving this goal (although there may be other solutions too).
In the Welcome Files text box, instead of index.jsp enter just app, as if our default page was named 'app'. Let's see what will happen now if someone decides to navigate to our application's context: http://www.example.com/FirstTapestry/. To decide which page to show, Tomcat will look into the application's deployment descriptor: what is the welcome file? Hmm... There should be some file named 'app'. Let's try it then -- and Tomcat will pass the request to http://www.example.com/FirstTapestry/app, which is exactly the path to which the Tapestry servlet is mapped, so our Tapestry application will handle the request properly.
For now, save the deployment descriptor with all the changes. You can also delete the index.jsp page, as it is not needed anymore.
We have finished with configuration issues and have arrived at the most interesting step -- creating the application itself.