Chapter 2: Your First Tapestry Application

Before we can get down to the fun, we have to create an empty application. Tapestry uses a feature of Maven to do this: archetypes (a too-clever way of saying "project templates").

What we'll do is create an empty shell application using Maven, then import the application into Eclipse to do the rest of the work.

For the tutorial, I've used a fresh install of Eclipse and an empty workspace at /Users/Howard/Documents/workspace ¹ . You may need to adjust a few things for other operating systems or local paths.

From my workspace directory, I'll use Maven to create a skeleton Tapestry project.

Before proceeding, we have to decide on four things: A Maven group id and artifact id for our project, a version, and a base package name.

Maven uses the group id and artifact id to provide a unique identity for the application, and Tapestry needs to have a base package name so it knows where to look for pages and components.

For this example, we'll use the group id com.example, artifact id tutorial1, version 1.0-SNAPSHOT and we'll use com.example.tutorial as the base package.

Our final command line is:

mvn archetype:generate -DarchetypeCatalog=http://tapestry.apache.org

It will then prompt you to pick the archetype - choose Tapestry 5.2.4 Quickstart Project, enter the group id, artifact id, version and package when prompted.

~/Documents/workspace
$ mvn archetype:generate -DarchetypeCatalog=http://tapestry.apache.org
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO]    task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] [archetype:generate {execution: default-cli}]
[INFO] Generating project in Interactive mode
[INFO] No archetype defined. Using maven-archetype-quickstart (org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
Choose archetype:
1: http://tapestry.apache.org -> quickstart (Tapestry 5.2.4 Quickstart Project)
2: http://tapestry.apache.org -> tapestry-archetype (Tapestry 4.1.6 Archetype)
Choose a number: : 1
Choose version: 
1: 5.1.0.5
2: 5.0.19
3: 5.2.4
Choose a number: 3: 3
Define value for property 'groupId': : com.example
Define value for property 'artifactId': : tutorial1
Define value for property 'version': 1.0-SNAPSHOT: 
Define value for property 'package': com.example: com.example.tutorial
Confirm properties configuration:
groupId: com.example
artifactId: tutorial1
version: 1.0-SNAPSHOT
package: com.example.tutorial
Y: 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 minute 41 seconds
[INFO] Finished at: Wed Nov 17 17:00:16 PST 2010
[INFO] Final Memory: 16M/81M
[INFO] ------------------------------------------------------------------------
~/Documents/workspace
$ 

After executing the command, you'll see a new directory, tutorial1.

<settings>
  <proxies>
    <proxy>
      <active>true</active>
      <protocol>http</protocol>
      <host>myProxyServer.com</host>
      <port>8080</port>
      <username>joeuser</username>
      <password>myPassword</password>
      <nonProxyHosts></nonProxyHosts>
    </proxy>
  </proxies>
  <localRepository>C:/Documents and Settings/joeuser/.m2/repository</localRepository>
</settings>

Running the New Application in Jetty

One of the first things you can do is use Maven to run Jetty directly.

Change into the newly created directory, and execute the command:

mvn jetty:run

Again, the first time, there's a dizzying number of downloads, but before you know it, the Jetty servlet container is up and running.

Once Jetty is initialized (which only takes a few seconds), you'll see the following in your console:

                               URLRewriter: DEFINED
                         UpdateListenerHub: REAL
                    ValidateBindingFactory: DEFINED
             ValidationConstraintGenerator: DEFINED
                  ValidationMessagesSource: DEFINED
                            ValidatorMacro: DEFINED
                        ValueEncoderSource: DEFINED

85.00% unrealized services (153/180)

2010-11-17 17:06:30.630::INFO:  Started SelectChannelConnector@0.0.0.0:8080
[INFO] Started Jetty Server

You can now open a web browser to http://localhost:8080/tutorial1/ to see the running application:

The date and time in the middle of the page proves that this is a live application.

This is a complete little application; it doesn't do much, but it demonstrate how to create a number of pages sharing a common layout, and demonstrates some simple navigation.

Loading the Project into Eclipse

Let's look at what Maven has generated for us. To do this, we're going to load the project inside Eclipse and continue from there.

Start by hitting Control-C in the Terminal window to close down Jetty.

Next, we'll ask Maven to create our Eclipse project for us:

$ mvn eclipse:eclipse -DdownloadSources=true
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'eclipse'.
[INFO] org.apache.maven.plugins: checking for updates from apache-snapshots
[INFO] org.codehaus.mojo: checking for updates from apache-snapshots
[INFO] artifact org.apache.maven.plugins:maven-eclipse-plugin: checking for updates from apache-snapshots
[INFO] snapshot org.apache.maven.plugins:maven-eclipse-plugin:2.9-SNAPSHOT: checking for updates from apache-snapshots
Downloading: http://repository.apache.org/snapshots//org/apache/maven/plugins/maven-eclipse-plugin/2.9-SNAPSHOT/maven-eclipse-plugin-2.9-20101117.070458-148.pom
11K downloaded  (maven-eclipse-plugin-2.9-20101117.070458-148.pom)
Downloading: http://repository.apache.org/snapshots//org/apache/maven/plugins/maven-eclipse-plugin/2.9-SNAPSHOT/maven-eclipse-plugin-2.9-20101117.070458-148.jar
194K downloaded  (maven-eclipse-plugin-2.9-20101117.070458-148.jar)
[INFO] ------------------------------------------------------------------------
[INFO] Building tutorial1 Tapestry 5 Application
[INFO]    task-segment: [eclipse:eclipse]
[INFO] ------------------------------------------------------------------------
[INFO] Preparing eclipse:eclipse
[INFO] No goals needed for project - skipping
[INFO] [eclipse:eclipse {execution: default-cli}]
[INFO] Using Eclipse Workspace: /Users/Howard/Documents/workspace
[INFO] Adding default classpath container: org.eclipse.jdt.launching.JRE_CONTAINER
[INFO] Wrote settings to /Users/Howard/Documents/workspace/tutorial1/.settings/org.eclipse.jdt.core.prefs
[INFO] Wrote Eclipse project for "tutorial1" to /Users/Howard/Documents/workspace/tutorial1.
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5 seconds
[INFO] Finished at: Wed Nov 17 17:13:11 PST 2010
[INFO] Final Memory: 21M/81M
[INFO] ------------------------------------------------------------------------
~/Documents/workspace/tutorial1
$ 

At this point, Maven has created the Eclipse .project and .classpath files, and we can import the project.

Launch Eclipse and switch over to the Java Perspective.

Right click inside the Package Explorer view and select Import ...

Choose the "existing projects" option:

Now select the folder created by Maven:

When you click the Finish button, the project will be imported into the Eclipse workspace.

However; there are many errors. Maven expects that you will configure a classpath variable, M2_REPO, that points at your local repository; a directory in your home directory that stores all those downloaded JARs and other files. Open Eclipse's preferences panel and navigate to Java > Build Path > Classpath Variables:

Click the New button, and enter the new variable (you'll have to adjust this for your operating system and local paths):

Eclipse will ask to perform a clean build, and the errors will be gone once it has done so.

Investigating the Generated Artifacts

Maven dictates the layout of the project:

• Java source files under src/main/java
• Web application files under src/main/webapp (including src/main/webapp/WEB-INF)
• Java test sources under src/test/java
• Non-code resources under src/main/resources and src/test/resources

Let's look at what the archetype has created for us, starting with the web.xml configuration file:

<?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>tutorial1 Tapestry 5 Application</display-name>
    <context-param>
        <!-- The only significant configuration for Tapestry 5, this informs Tapestry
of where to look for pages, components and mixins. -->
        <param-name>tapestry.app-package</param-name>
        <param-value>com.example.tutorial</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>

This is short and sweet: you can see that the package name you provided earlier shows up as the tapestry.app-package context parameter; the TapestryFilter instance will use this information to locate the Java classes for pages and components.

Tapestry 5 operates as a servlet filter rather than as a traditional servlet. In this way, Tapestry has a chance to intercept all incoming requests, to determine which ones apply to Tapestry pages (or other resources). The net effect is that you don't have to maintain any additional configuration for Tapestry to operate, regardless of how many pages or components you add to your application.

Tapestry pages minimally consist of an ordinary Java class plus a component template file.

In the root of your web application, a page named "Index" will be used for any request that specifies no additional path after the context name. Tapestry expects pages to be stored in the pages package under your root package; in this case, the class name will be com.example.tutorial.pages.Index.

Tapestry pages are the combination of a POJO Java class with a Tapestry component template. The has the same name as the Java class, but has the extension .tml. Since the Java class here is com.example.tutorial.pages.Index, the template file will be located at src/main/resource/com/example/tutorial/pages/Index.tml.

Tapestry component templates are well-formed XML documents. This means that you can use any available XML editor. Templates may even have a DOCTYPE or an XML schema to validate the structure of the template.

For the most part, the template looks like ordinary XHTML:

<html t:type="layout" title="tutorial1 Index"
      t:sidebarTitle="Current Time"
      xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
      xmlns:p="tapestry:parameter">
        <!-- Most of the page content, including <head>, <body>, etc. tags, comes from Layout.tml -->

    <p>${message:greeting}</p>

    <p:sidebar>

        <p>
            Just to prove this is live:
        </p>

        <p>The current time is: ${currentTime}.</p>


        <p>
            [<t:pagelink page="Index">refresh</t:pagelink>]
        </p>
    </p:sidebar>

</html>

The goal in Tapestry is for component templates, such as Index.tml, to look as much as possible like ordinary, static HTML files ² . In fact, the expectation is that in many cases, the templates will start as static HTML files, created by a web developer, and then be instrumented to act as live Tapestry pages.

Tapestry hides non-standard element and attributes inside the XML namespace. By convention, the prefix "t:" is used for the primary namespace, but that is not a requirement.

This short template demonstrates quite a few features of Tapestry.

First of all, there are two XML namespaces defined:

  xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
  xmlns:p="tapestry:parameter"

The first namespace, "t:", it used to identify Tapestry-specific elements and attributes. Although there is an XSD (that is, a XML schema definition), it is incomplete (for reasons explained shortly).

The second namespace, "p:", is a way of marking a chunk of the template as a parameter passed into another component. We'll expand on that shortly.

A Tapestry template consists mostly of standard XHTML that will pass down to the client web browser unchanged. The dynamic aspects of the template are represented by components and expansions.

Components can be represented two ways:

• As an ordinary element, but with a t:type attribute to define the type of component.

• As an element in the Tapestry namespace, in which case the element name determines the type.

In nearly all cases, the two approaches are equivalent.

Here we've used an <html> element to represent the application's Layout component.

<html t:type="layout"> 
  ...
</html>

But for the PageLink component, we've used an element in the Tapestry namespace:

<t:pagelink> ... </t:pagelink>

Which form you use is a matter of choice. In the vast majority of cases, they are exactly equivalent.

Tapestry components are configured using parameters; for each component, there is a set of parameters, each with a specific type and purpose. Some parameters are required, others are optional. Attributes of the element are used to bind parameters to values, or to page properties. Tapestry is flexible here as well; you can always place an attribute in the Tapestry namespace (using the "t:" prefix), but in most cases, this is unecessary.

<html t:type="layout" title="tutorial1 Index"
      t:sidebarTitle="Current Time"

This binds two parameters, title and sidebarTitle of the Layout component, to the literal strings "tutorial1 Index" and "Current Time", respectively.

First is the way we display the current date and time: ${currentTime}. This syntax is used to access a property of the page object, a property named currentTime. Tapestry calls this an expansion. The value inside the braces is the name of a standard JavaBeans property supplied by the page. As we'll see in later chapters, this is just the tip of the iceberg for what is possible using expansions.

The other dynamic element is the link used to refresh the page. We're specifying a component as an XML element within the Tapestry namespace. The element name, "pagelink", defines the type of component. PageLink (Tapestry is case insensitive) is a component built into the framework; it is part of the Tapestry core component library. The attribute, page, is a string - the name of the page to link to. Here, we're linking back to the same page, page "Index".

This is how Tapestry works; the Index page contains an instance of the PageLink component. The PageLink component is configured via its parameters, which controls what it does and how it behaves.

The URL that the PageLink component will render out is http://localhost:8080/tapestry-tutorial1/. "Index" pages are special and are identified just by the folder name. In later examples, when we link to pages besides "Index", the page name will be part of the URL.

Tapestry ignores case where ever it can. Inside the template, we configured the PageLink component's page parameter with the name of the page, "Index". Here too we could be fuzzy on case. Feel free to use "index" if that works for you.

Clicking the link in the web browser sends a request to re-render the page; the template and Java object are re-used to generate the HTML sent to the browser, which results in the updated time showing up in the web browser.

The final piece of the puzzle is the Java class for the page. Tapestry has very specific rules for where page classes go. Remember the package name (configured inside web.xml)? Tapestry adds a sub-package, "pages", to it and the Java class goes there. Thus the full Java class name is org.apache.tapestry5.tutorial.pages.Index.

package org.apache.tapestry5.tutorial.pages;

import java.util.Date;

/**
 * Start page of application tutorial1.
 */
public class Index
{
  public Date getCurrentTime()
  {
    return new Date();
  }
}

That's pretty darn simple: No classes to extend, no interfaces to implement, just a very pure POJO (Plain Old Java Object). You do have to meet the Tapestry framework halfway:

• You need to put the Java class in the expected package, org.apache.tapestry5.tutorial.pages
• The class must be public
• You need to make sure there's a public, no-arguments constructor (here, the Java compiler has silently provided one for us)

The template referenced the property currentTime and we're providing that as a property, as a synthetic property, a property that is computed on the fly (rather than stored in an instance variable).

This means that every time the page renders, a fresh Date instance is created, which is just what we want.

As the page renders, it generates the HTML markup that is sent to the client web browser. For most of the page, that markup is exactly what came out of the component template: this is called the static content (we're using the term "static" to mean "unchanging").

The expansion, ${currentTime}, is dynamic: different every time. Tapestry will read that property and convert the result into a string, and that string is mixed into the stream of markup sent to the client. _We'll often talk about the "client" and we don't mean the people you send your invoices to: we're talking about the client web browser. Of course, in a world of web spiders and other screen scrapers, there's no guarantee that the thing on the other end of the HTTP pipe is really a web browser. ³ . Likewise, the PageLink component is dynamic, in that it generates a URL that is (potentially) different every time.

Tapestry follows the rules defined by Sun's JavaBeans specification: a property name of currentTime maps to two methods: getCurrentTime() and setCurrentTime(). If you omit one of the other of these methods, the property is either read only (as here), or write only ⁴ .

Tapestry does go one step further: it ignores case when matching properties inside the expansion to properties of the page. In the template we could say ${currenttime} or ${CurrentTime} or any variation, and Tapestry will still invoke the getCurrentTime() method.

In the next chapter, we'll start to build a simple hi-lo guessing game, but we've got one more task before then, plus a magic trick.

The task is to set up Jetty to run our application directly out of our Eclipse workspace. This is a great way to develop web applications, since we don't want to have to use Maven to compile and run the application ... or worse yet, use Maven to package and deploy the application. That's for later, when we want to put the application into production. For development, we want a fast, agile environment that can keep up with our changes, and that means we can't wait for redeploys and restarts.

Choose the Run ... item from the Eclipse Run menu to get the launch configuration dialog:

Select Jetty Web and click the New button:

We've filled in a name for our launch configuration, and identified the project. We've also told Jetty Launcher where our Jetty installation is. We've identified the web context as src/main/webapp, and we've turned on NCSA logging for good measure.

In addition, we've set up the context as "/tutorial1", which matches what our eventual WAR file, tutorial1.war, would be deployed as inside an application server.

Once you click Run, Jetty will start up and launch (it should take about two seconds).

You may now start the application with the URL http://localhost:8080/tutorial1/.

A Magic Trick

Now it's time for the magic trick. Edit Index.java and change the getCurrentTime() method to:

  public String getCurrentTime()
  {
    return "A great day to learn Tapestry";
  }

Make sure you save changes; then click the refresh link in the web browser:

This is one of Tapestry's early wow factor features: changes to your component classes are picked up immediately. No restart. No re-deploy. Make the changes and see them now. Nothing should slow you down or get in the way of you getting your job done.

Now that we have our basic application set up, and ready to run (or debug) directly inside Eclipse, we can start working on implementing our Hi/Lo game in earnest.

1. Yes, I'm on a Mac. Get one. ↩
2. By static, we mean unchanging, as opposed to a dynamically generated Tapestry page. ↩
3. You'll often see low-level HTML and HTTP documentation talk about the "user agent" rather than the "browser". ↩
4. Keep in mind that as far as JavaBeans properties go, it's the methods that count; the names of the instance variables, or even whether they exist, is immaterial. ↩

Continue on to chapter 3: Implementing The Hi/Lo Game