Task 2 – Explore the Tapestry 5 project structure and learn where to put your stuff

This post is a continuation of the previous one.

Let’s expand all the nodes of the project in the Package Explorer.

If you have never seen a project structure for a web application by Maven convention – this is it. Well, with Tapestry flavor. This “tree of files” is created by tapestry quickstart archetype.

Two sentences of theory before continuing.

It is WHERE the files END UP in the WAR that matters, not where they are in your development environment. The IDE and tools that you use should maximize the productivity and harness the power that is provided by Tapestry framework.

I will continue to describe one project layout with one set of tools in this post. I want to describe things simple. I will rather create another post for different set of tools and/or personal preferences of where things (files) can be.

The tools of choice are: Eclipse (3.4.0), Maven (2.0.9) and m2eclipse plugin (0.9.6).

As we are not starting from scratch – the archetype did the initial work for us – let’s have a look at the existing directories and files from top to bottom.

There are two java files in two different packages: Index.java and AppModule.java. The Index.java resides in the org.driving.school.pages package and it is in this package that you will add java sources for additional pages you will create. The AppModule.java is a Tapestry Inversion of Control Module. This is your application’s module builder class. In other words – it is where you will do most of the configuration.

The accompanying template file to the Index.java controller class is Index.tml. In the above figure it is located in the src/main/webapp/ directory. This file can also reside in src/main/resources/org/driving/school/pages directory. It is of personal/team CHOICE where the template files are located.

So, what else goes to src/main/resources? As you can observe from the figure above, the log4j.properties file is one of them. Why? Because when packaged, it ends up in the WEB-INF/classes, which means on the classpath. Message catalogs (.properties) also belong here.

You can imagine what goes to src/test/java and src/test/resources. I will not go into details here because this is not a crash course in Test Driven Development.

Next, there are two libraries: JRE System Library and Maven Dependencies. The latter includes all the jars needed by the project. Only two of them are really referenced in the project’s POM: tapestry-core and testng. The others are so called transitive dependencies (dependencies of dependencies). Maven takes care of downloading and including them in the classpath.

We will skip src/main/webapp/META-INF/MANIFEST.MF.

And then there is app.properties file under src/main/webapp/WEB-INF. This is a global message catalog. It will include a default language messages. They are called messages because you will be accessing them through the message prefix, but we will not discuss that now. If your application will be multilingual then you would create a file, for example, app_sl_SI.properties which would include Slovenian messages (translations).

Next, the only XML file you will need to have in your application – web.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
   "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<display-name>school Tapestry 5 Application</display-name>
<context-param>
   <param-name>tapestry.app-package</param-name>
   <param-value>org.driving.school</param-value>
</context-param>
<filter>
   <filter-name>app</filter-name>
   <filter-class>org.apache.tapestry5.TapestryFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>app</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>

There is one context parameter. It has a value of org.driving.school. This tells Tapestry where to look for pages and components. That is why you have a package named org.driving.school.pages under src/main/java.

You can also see there is a filter named app which is implemented by TapestryFilter class. Every request that comes to application’s context (in our case http://localhost:8080/school) is processed by TapestryFilter.

Favicon.ico is a file which I think everyone knows what it is, so we will skip it.

Now the template file for the page – Index.tml. I have already mentioned it above. This is a XHTML file which includes elements in Tapestry namespace

xmlns:t=http://tapestry.apache.org/schema/tapestry_5_0_0.xsd

like

<t:pagelink page="Index">refresh</t:pagelink>

The tml files are the View part of your app and those files will be the only ones developers will meet the designers. With very little practice no one will ruin the work of the other one. There is of course a lot more to tell for the templates, but as this blog is about hands-on approach to building web apps, I have to be short in words and more expressive in examples and real world cases.

One file remains – pom.xml. This is a Maven thing. It manages our project. It is here where you configure what java libraries do we need, and what version of the compiler to use, and what should be the name of the WAR (hence context name) etc.

It includes a jetty plugin which enables us to run the web app with mvn jetty:run, but unfortunately Windows users will have to do a bit more to achieve that changing something in the CSS will be visible in the browser without restarting the Jetty container. Yes, something as basic as that and it does not work out of the box by pressing F5 (refresh) in the browser. I was quite disappointed until I dug the solution on the net. I will write about this in the next post.

The quickstart archetype is really just that – quick. It does not demonstrate the users (developers) where components are, where images and css files should be, how pages can be grouped in subfolders/subpackages and a lot of other concepts. Of course this is all explained at official site, but in many cases in a technical lingo which does not suit everyone well, especially newbies. Several more archetypes should be created and made available to public via Maven repositories which would demonstrate and kick start a new project with some additional concepts.

So, to achieve the Task 2 I have to explain where to put your components. The java files for this project would go under src/main/java/org/driving/school/components and the resources (templates, message catalogs, javascript) under src/main/resources/org/driving/school/components.

Put your images in the src/main/webapp/images (or img or similar) and CSS files as a sibling to images (src/main/webapp/css).

This post ends here. It does not provide much value as we have only walked through the files of the quickstart project template, but it pointed out to some weak points which will all be addressed in the next posts. The goal is to remove the pit holes some of us have fallen into when started to use Tapestry 5.

Task 1 - Create a skeleton Tapestry 5 project and run it.

Fire up Eclipse Ganymede and choose Java perspective. Make sure the eclipse is started up with JDK not JRE.

Select File/New/Other… from the Eclipse menu. In the dialog type maven in the Wizard's input field to reduce the number of wizards in the list. Select Maven Project.


In the New Maven Project dialog that appears next just click Next. Don’t get distracted by other options for now.


After clicking Next, you will see something similar like the image bellow.


In short - there are numerous so called archetypes (maven terminology for project templates) in the list which are identified by GroupId, ArtifactId and Version. Archetypes are “gathered” in catalogs and one of them is Nexus Indexer which includes all archetypes from the central maven repository.

If you don’t see any artifacts, then you don’t have central index downloaded or you haven’t chosen to include an optional component Maven Central repository index while installing m2eclipse plugin.

If you do see the artifacts, then you can skip the next two screenshots.

Check Software Updates and Add-ons in Help/Software updates… menu in Eclipse to confirm you have all the necessary components installed.

If you don’t have Maven Central repository index in the list of Installed Software, then select Available Software tab and install it by selecting this/these module(s) under Maven Integration for Eclipse Update Site.

To automatically download Nexus index (which includes Tapestry 5 archetypes) at Eclipse startup check Download repository index updates on startup in the Preferences.


Now let's continue. We are looking for Tapestry 5 archetype, so type tapestry in the Filter input field.


Select quickstart archetype, at present (December 2008) the version 5.0.18 is available. Click Next.

Now the New Maven Project Wizard displays a dialog which asks us about the name of the project. Name is not the right term in Maven world, but we will not go too deeply into theory for now, let’s just type org.driving for the GroupId and school for ArtifactId. Leave the Version as is.


Click Finish.

After a few moments you should see something very similar to the image below in the Package Explorer.

If you don’t have a Console View in your Java Perspective, please add it (Window/Show View/Console). Choose Maven Console.


Let’s stay focused. The task is to create a basic Tapestry 5 skeleton application and run it. Let’s do that!

Select Run Configurations… from the Run Menu Command.


This will open up the Run Configurations dialog. Locate and select Maven Build and then press the New button.


Now fill in the missing blanks in the next dialog. Name this Run Configuration with something meaningful, like Run Traffic School. The fill in the Base Directory by clicking the Browse Workspace button and selecting the school project. Type jetty:run for the Goal input field. Then click Run and wait for Maven to download all the necessary artifacts. This can take some time the first time, but the next time the Jetty will launch very quickly.


If all goes well, you should see something like this in the Maven Console:


Open your browser and type http://localhost:8080/school

You should see


You can click the refresh link and see the time changes – just to prove it works. You can stop the Jetty server by clicking on the red square in the Maven Console. This ends this task.

You learned how to create a new Tapestry 5 skeleton project by running New Maven Project wizard and how to run the Tapestry 5 web application by creating a maven run configuration.

Alternative approaches

You can create a Tapestry 5 skeleton project by running
mvn archetype:create
-DarchetypeGroupId=org.apache.tapestry
-DarchetypeArtifactId=quickstart
-DgroupId=org.driving
-DartifactId=school
-DpackageName=org.driving.school

You can run the application with

mvn jetty:run or with mvn tomcat:run

You can also run the web application with WTP (Web Tools Project) by right clicking on a project and selecting Run As / Run on Server.

If you haven’t defined a server yet or even not downloaded one, then you have some more work to do. Choose the server (Tomcat 6.0 for example).


In the next step choose the directory of the Tomcat you have downloaded and unzipped to.


After clicking on Next, a dialog appears which shows which projects can be run on this Tomcat server.


Our project is already configured, so just click Finish. The Tapestry 5 project will be launched and first page displayed in the embedded browser inside Eclipse.


Running with Tomcat with WTP causes the Tomcat container to reload the context (by default) on any file change in the context path. This is sometimes not desirable as it hides the jewel of Tapestry – live class reloading. To be discussed in the next task.

Tapestry 5 - Setting up the environment

Tools stack: Eclipse Ganymede, Maven 2, m2eclipse Maven Eclipse plugin

1. Install JDK 1.5 or greater
2. Download Eclipse IDE for Java EE Developers
3. Install Maven 2
4. Install m2eclipse plugin

This is by no means the only possible stack. You can develop Tapestry 5 web applications with any IDE you can think of, even plain notepad if you wish. Of course with Java editors and refactoring capabilities of modern IDEs such as NetBeans, IDEA and Eclipse raises your productivity to a next level.

Also, Maven is not mandatory, you can use any build tool you wish.

Hopefully, as time permits, I will post Tapestry 5 releated stuff in this blog. I will follow my moto as in this latin proverb: "By learning you will teach, by teaching you will learn.".