Page History

...

For this example, we'll use the group id org.apache.tapestry*, artifact id tapestry-tutorial1, version 1.0-SNAPSHOT and we'll use org.apache.tapestry5.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 quickstart, enter the group id, artifact id, version and package when prompted.

...

The first time you execute this command, Maven will spend quite a while downloading all kinds of JARs into your local repository, which can take a minute or more. Later, once all that is already available locally, the whole command executes in under a second.

Using Maven Behind a Firewall

If you are behind a firewall, before running any "mvn" commands, you will need to configure your proxy settings in settings.xml. Here is an example:

<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>

Of course, adjust the <localRepository> localRepository element to match the correct path for your computer.

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.

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

Image ModifiedDefault Start page for Application

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

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.

...

Choose the "existing projects" option:

Image ModifiedImport Project into Eclipse

Now select the folder created by Maven:

Image ModifiedSelect folder to import

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

TODO: Picture of Java Browsing Perspective

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 (

...

Investigating the Generated Artifacts

Let's look at what the archetype has created for us, starting with the web.xml 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>org.apache.tapestry5.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 we'll look at next.

...

Let's start with the template, which is stored in the webapp's WEB-INF folder. 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. That is, your build process may use a tool to validate your templates. At runtime, when Tapestry reads the template, it does not use a validating parser. For the most part, the template looks like ordinary XHTML:

...

<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
    <head>
        <title>tutorial1 Start Page</title>
    </head>
    <body>
        <h1>tutorial1 Start Page</h1>

        <p> This is the start page for this application, a good place to start your modifications.
            Just to prove this is live: </p>

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


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

The goal in Tapestry is for component templates, such as Index.tml, to look as much as possible like ordinary, static HTML files.

...

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 item 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".

...

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 inexact 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.

...

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.

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.

...

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

Image Modified

Eclipse Run Dialog

Select Jetty Web and click the New button:

Image ModifiedEclipse Launch Configuration

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.

...

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:

Image ModifiedApplication after live class reloading

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.

...

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