Weaving the Tapestry Framework

Monday Oct 24th 2005 by Vlad Kofman

Walk thought the basic concepts of the Tapestry framework, config files, and setup then create a sample project in an enterprise-scale IDE such as JBuilder.

In a continuation of my series of articles about Java Web development frameworks, this article will look at the Tapestry framework. Because Tapestry is a rather large framework, one article is not enough to cover most of its features. I decided to split the discussion about Tapestry into two parts. In this first part, I will focus on the configuration of the framework in an enterprise-level IDE such as JBuilder 2005 and prepare the groundwork for a working example in the second part. I will also describe the structure of the framework and its main features in this article, and concentrate on more specific features and details in the second part.

Background of Tapestry

Tapestry is an open-source framework for Web development written in Java. It competes with other frameworks such as Struts, WebWork, and Turbine to be the first choice of Web developers as an application framework. It was developed by Howard Lewis Ship and is part of Jakarta project at Apache Software Foundation.

Tapestry is not like the other Web development frameworks, not only in terms of its structure and APIs but also in terms of the development process. It uses a component object model to represent the pages of a Web application. Working with Tapestry feels more like developing a desktop application with Graphical User Interface (GUI) widgets or java Swing components. Under the hood framework is written cleverly enough to make coding a Web application feel as a desktop application development. The framework does a tremendous amount of work behind the scenes and hidden from the developers, such as object pooling, multi threading, listener callbacks, garbage collections, session state, rendering, and other processes.

At first glance, Tapestry may appear to be overly complex and resource intensive; however, it actually is not. Most of the components are cached or reused and structure is intuitive for any developer who has worked with Swing or a similar GUI toolkit. The framework also uses XML intensively.

Tapestry implements the Model-View-Controller (MVC) paradigm not only for the overall separation of logic and presentation at the framework level, but also on the level of its individual components such as tables or forms, as I will explain in the next section. Additionally, numerous main components are implemented in terms of public interfaces to give developers a great deal of flexibility in using the framework.

Tapestry also offers a built-in logging mechanism that is excellent. It is extremely flexible and provides a wealth of information.

Here is a short description of the framework from the Apache site:

Tapestry reconceptualizes Web application development in terms of objects, methods, and properties instead of URLs and query parameters.

Tapestry is an alternative to scripting environments such as JavaServer Pages or Velocity. Tapestry goes far further, providing a complete framework for creating extremely dynamic applications with minimal amounts of coding.

Tapestry's approach, using a component object model similar to a traditional GUI, provides the following benefits:

  • Very high level of reuse, within and between projects
    Everything in Tapestry is a reusable component
  • Frees developers from writing boring, buggy code
    Code in terms of objects, methods, and properties, not URLs and query parameters
  • Allows applications' complexity to scale well
    Framework does all the URL building and message dispatching, transparently
  • Easy Internationalization/Localization
    Framework selects localized version of text, templates, and images
  • Extremely robust applications
    Less code is less bugs
    Sophisticated built-in exception reporting
    Line precise error reporting
  • Easy team integration
    Graphic designers and Java developers can work together without having to know each other's jobs

Tapestry components are a combination of a specification file (in XML), an HTML template, and a Java class (extending a framework class, with simple additions). Tapestry components are combined together to form larger components or complete Tapestry pages.

Structure of the Framework

"The goal of Tapestry is to eliminate most of the coding in a Web application. Under Tapestry, nearly all code is directly related to application functionality, with very little "plumbing." If you have previously developed a Web application using PHP, Microsoft Active Server Pages, JavaServer Pages, or Java Servlets, you may take all the plumbing for granted: writing servlets, assembling URLs, parsing URLs, managing objects inside the HttpSession, and so forth. Tapestry takes care of nearly all of that, for free. It allows for the development of rich, highly interactive applications." (Kevin C. Dorff, Tapestry online tutorial)

Similar to other Web development frameworks, Tapestry is configured via a set of XML property files and other resource files. There is a main [your-app-name].application config file, a set of custom application specific "jwc" and "page" resource files, and a traditional controller Servlet. But, this is where the resemblance to other MVC frameworks ends. A concept of Application Engine, a view rendering process, and templates makes Tapestry feel very different and stand our from the pack.

Every HTML page that the user sees is rendered from a template by the application engine that is initialized per user session. Additionally, view objects follow an MVC pattern and have data models with states that can be changed. For example, forms can have listeners attached to them or tables could be "restored" to a previous state.

Setup and Configuration

Before I discuss the inner working and the main components of the framework, I want to talk about the development environment and its setup.

For this article and the example in the second part, I'm using BEA WebLogic application server, JBuilder 2005 as the development IDE, and a free MySQL database for my database needs. Because J2EE has a standardized WAR and EAR packaging structure, you may use any other application server such as Apache Tomcat, any other IDE such as very popular and free Eclipse and any other database. Assuming you are savvy enough with using other tools and can comfortably create a WAR module, get it running on an application server, and connect to a database, all of my examples should work with minimal changes. But, descriptions and screenshots will reference my environment.

Note: As of this writing, Tapestry is up to version 3.0.3 and MySQL database at version 4.1 with Connector/J mysql-connector-java-3.1.11-bin.jar.

To set up Tapestry, download it at http://jakarta.apache.org/tapestry/downloads.html.

Create a new Project (call it Tapestry) in JBuilder and add Tapestry and MySQL connection libs into the project class-path.

Assuming you have installed and configured BEA WebLogic with JBuilder, assign a server to the project.

Next, create a new directory "resources." In this directory, I have placed all property and config files necessary for the sample application, including the main ".application" file. These files can be placed directly in the WEB-INF, but for convenience they have their own directory. Create a couple of empty text files with actual names such as "first-tapestry-app.application", "Home.page," and "Next.page" in that folder (you will add contents to these files later).

Create a Web Module—TapesryWebModule—in JBuilder and configure it to include all libs in the WAR file build process and these resources.

Click here for a larger image.

Click here for a larger image.

Assuming you also have downloaded MySql and installed it, this is all that is needed for the configuration of the development environment for now.

The final project should look something like this:

Main Components

Here is a very general structure of the framework.

  1. The Application Servlet is invoked by the Web container.
  2. It creates an Application Engine object on behalf of each user.
  3. The Application Engine reads the main application config file.
  4. The Application Engine reads property files.
  5. The Application Engine renders a HTML view from a template.

Look at the configuration files before continuing to see the data flow and structure. The standard web.xml file for the WAR module of the sample Tapestry application can look like a very common config file for any WAR file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
   PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

</servlet-mapping> </web-app>

Here, I defined a servlet called "Controller" that extends org.apache.tapestry. ApplicationServlet (note that there have been a lot of changes between Tapestry versions 2 and 3, including a package structure in version 2 ApplicationServlet was under net.sf.tapestry.ApplicationServlet), and also mapped the servlet name. A subclass servlet is needed only if you want to customize the options and path. Tapesry's main servlet has several methods, such as getApplicationSpecificationPath, that can be overwritten. If you have no need to change these settings, you can use the ApplicationServlet directly. (Also note that the setupLogging method is no longer available in version 3.)

public class Controller
      extends ApplicationServlet {
   private static Logger logger = Logger.getLogger(Controller.class);
   public Controller() {
   protected String getApplicationSpecificationPath() {
      return "/resources/first-tapestry-app.application";

As I mentioned, any Tapestry application also needs a main "application" config file. For example, the "first-tapestry-app.application" XML file located in the application server class path. You now can add contents to this file that is under the directory called "resources." It will end up under the "WEB-INF -> classes" directory of the WAR module.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE application PUBLIC
   "-//Howard Lewis Ship//Tapestry Specification 1.3//EN"
<application name="first-tapestry-app"
   engine-class=" org.apache.tapestry.engine.BaseEngine">
   <property name="driverClass">com.mysql.jdbc.Driver</property>
   <property name="dbUrl">jdbc:mysql://localhost/test</property>
   <property name="user">root</property>
   <property name="password">password</property>
   <page name="Home" specification-path="/resources/Home.page"/>

The first-tapestry-app.application file is very simple; you give the application name, use the standard engine, and define a single page, named "Home." In Tapestry, pages and components are specified with the path to their specification file (a file that ends with ".page" for page specifications or ".jwc" for component specifications).

The page named "Home" has a special meaning to Tapestry: When you first launch a Tapestry application, it loads and displays the "Home" page. All Tapestry applications are required to have such a page.

Note: In previous versions of Tapestry, it was required to list all of application pages in the .application file. In Tapestry 3.0, it is necessary only to list the "Home" page.

The "JWC" stands for java Web components and "page" files are XML files that describe structure of the HTML file.

In Tapestry, every HTML page that the user sees is rendered dynamically and consists of at least three pieces. One piece is an HTML template file that is pure HTML with place holders for Tapestry components. The second piece is the XML specification "page" file that defines what will go (and be done) with the final HTML. The third piece is usually a corresponding Java Class. There could be many more "helper" files, defining individual JWC components, and so on.

The Home page specification could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE page-specification
PUBLIC "-//Apache Software Foundation//Tapestry Specification 3.0//EN"
<page-specification class="org.apache.tapestry.html.BasePage">
   <description> Simple Home Page </description>

The corresponding Home.html could look like this:

<title>Simple Home Page</title>
   Welcome to your first <b>Tapestry Application</b>.

The application will compile and run but it's not very exciting; there's no dynamic content. A very interesting observation is that there was no JavaServer page (JSP) here, and no HTML directly visible to the Web server. Tapestry assembled an application consisting of a single component on the fly and presented it to the user. This is one of the greatest differences between Tapestry and other Web development frameworks. Additionally, these created objects and pooled and reused, which makes this framework very scalable.


In this article, I have described the basic concepts of the Tapestry framework. I have decided to split my discussion about the framework in to two parts because I feel it's too large and complex for one article. I have shown how to create a sample project in an enterprise-scale IDE such as JBuilder and talked about framework config files and setup. In the next part of this article, I will show you how to create a real dynamic example that communicates to a RDBM source and uses more Tapestry components.



Wikipedia online: http://en.wikipedia.org/wiki/

Tapestry (general): http://jakarta.apache.org/tapestry/

Tapestry online tutorial


Neal Ford: Art of Java Web Development: Struts, Tapestry, Commons, Velocity, JUnit, Axis, Cocoon, InternetBeans, WebWork (Paperback), ISBN 1932394060

About the Author

Vlad Kofman is a Senior System Architect implementing enterprise-scale projects for the major Wall Street firms, projects under defense contracts and the U.S. government. His main interests are object-oriented programming methodologies and design patterns.

Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved